From 7aa476c302e3e59ef73588a3d2ca7c2a89910ed9 Mon Sep 17 00:00:00 2001 From: Aptimex Date: Fri, 6 Sep 2024 12:36:35 -0600 Subject: [PATCH 01/22] ci fix attempt --- .github/workflows/goreleaser.yml | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/.github/workflows/goreleaser.yml b/.github/workflows/goreleaser.yml index ad03792..eaba7fe 100644 --- a/.github/workflows/goreleaser.yml +++ b/.github/workflows/goreleaser.yml @@ -8,7 +8,12 @@ on: jobs: goreleaser: runs-on: ubuntu-latest + env: + flags: "" steps: + - if: ${{ !startsWith(github.ref, 'refs/tags/v') }} + # Allows manually running this on an untagged commit without actually generating a release + run: echo "flags=--snapshot" >> $GITHUB_ENV - name: Checkout uses: actions/checkout@v4 with: @@ -19,22 +24,13 @@ jobs: go-version: "1.20" cache: true cache-dependency-path: src/go.sum - - name: Check GoReleaser Config - uses: goreleaser/goreleaser-action@v6 - with: - distribution: goreleaser - version: latest - args: check - workdir: ./src - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Run GoReleaser uses: goreleaser/goreleaser-action@v6 with: # either 'goreleaser' (default) or 'goreleaser-pro' distribution: goreleaser - version: latest - args: release --clean + version: '~> v2' + args: release --clean ${{ env.flags }} workdir: ./src env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 4ec3064c1edb23c2219aed06569ba529deaf4550 Mon Sep 17 00:00:00 2001 From: Aptimex Date: Fri, 6 Sep 2024 12:47:50 -0600 Subject: [PATCH 02/22] fixed the real issues --- .github/workflows/goreleaser.yml | 9 +++++++++ src/.goreleaser.yaml | 3 ++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/.github/workflows/goreleaser.yml b/.github/workflows/goreleaser.yml index eaba7fe..69f69db 100644 --- a/.github/workflows/goreleaser.yml +++ b/.github/workflows/goreleaser.yml @@ -24,6 +24,15 @@ jobs: go-version: "1.20" cache: true cache-dependency-path: src/go.sum + - name: Check GoReleaser Config + uses: goreleaser/goreleaser-action@v6 + with: + distribution: goreleaser + version: '~> v2' + args: check + workdir: ./src + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Run GoReleaser uses: goreleaser/goreleaser-action@v6 with: diff --git a/src/.goreleaser.yaml b/src/.goreleaser.yaml index 9bc5004..8806a53 100644 --- a/src/.goreleaser.yaml +++ b/src/.goreleaser.yaml @@ -1,3 +1,4 @@ +version: 2 before: hooks: - go mod tidy @@ -25,7 +26,7 @@ archives: checksum: name_template: "checksums.txt" snapshot: - name_template: "{{ incpatch .Version }}-next" + version_template: "{{ incpatch .Version }}-next" changelog: use: github-native # sort: asc From fa26610e31503d9934900e03e17f36cfb31d92f0 Mon Sep 17 00:00:00 2001 From: Aptimex Date: Tue, 24 Sep 2024 18:11:06 -0600 Subject: [PATCH 03/22] First pass at README overhaul --- README.md | 346 ++++++++++++++++++------------------------------------ 1 file changed, 111 insertions(+), 235 deletions(-) diff --git a/README.md b/README.md index 2c0fd4c..c47b2cf 100644 --- a/README.md +++ b/README.md @@ -5,42 +5,94 @@ Wiretap is a transparent, VPN-like proxy server that tunnels traffic via WireGuard and requires no special privileges to run. -In this diagram, the client has generated and installed WireGuard configuration files that will route traffic destined for `10.0.0.0/24` through a WireGuard interface. Wiretap is then deployed to the server with a configuration that connects to the client as a WireGuard peer. The client can then interact with resources local to the server as if on the same network and chain additional servers to reach new networks. Access to the Wiretap network can also be shared with other clients. +In this diagram, the Client has generated and installed WireGuard configuration files that will route traffic destined for `10.0.0.0/24` through a WireGuard interface. Wiretap is then deployed to the Server with a configuration that connects to the Client as a WireGuard peer. The client can then interact with resources local to the Server as if on the same network, and optionally chain additional servers to reach new networks. Access to the Wiretap network can also be shared with other Clients.
![Wiretap Diagram](media/Wiretap_Animated.svg)
-## Quick Start +## Terminology and Requirements + +A Wiretap Server is any machine where a Wiretap binary is running the `serve` subcommand. Servers generate and receive network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." -1. Download binaries from the [releases](https://github.com/sandialabs/wiretap/releases) page, one for your client machine and one for your server (if different os/arch) -2. Run `./wiretap configure --port --endpoint --routes ` with the appropriate arguments -3. Import the resulting `wiretap.conf` and `wiretap_relay.conf` files into WireGuard on the client machine -4. Copy and paste the server command output that best suits your target system into Wiretap on the server machine -5. Add more servers and clients as needed with the `add` subcommand +A Wiretap Client is any machine running the Wireguard configurations necessary to send network traffic through a Wiretap server. It functions much like a client in a VPN connection. -## Requirements +> [!IMPORTANT] +> Unlike the typical use of "client" and "server" terms in networking, Wiretap's Client and Server terms have nothing to do with which machine listens for or initiates the initial connection. -### Client Systems +### Client System Requirements * WireGuard - https://www.wireguard.com/install/ -* Privileged access to configure WireGuard +* Privileged access necessary to configure WireGuard + + +### Server System Requirements + +* Ability to get the Wiretap binary onto the Server system, and run it + + +### Environment Requirements + +* Bidirectional UDP communication between Server and Client on one port. Any firewalls between them must allow at least one machine to initiate the UDP connection to the other. + * The machine receiving the initial connection (the Client by default) must be able to listen for UDP connections on a port that the initiating machine can connect to. -### Server Systems +> [!NOTE] +> By default the Server initiates the handshake to the Client because the Server is more likely to have outbound UDP allowed through a firewall than inbound UDP, but the reverse is easily configurable. + +While not ideal, Wiretap can still work with TCP instead of UDP. See the experimental [TCP Tunneling](#tcp-tunneling) section for more info. + +## Quick Start -* Bidirectional UDP access to client on one port. By default the server initiates the handshake to the client because it is more likely to have outbound UDP than inbound, but the reverse is easily configurable +1. Download binaries from the [releases](https://github.com/sandialabs/wiretap/releases) page, one for your Client machine and one for your Server machine (if different os/arch). Copy the Wiretap binary onto the server +2. On the Client, run `./wiretap configure --endpoint --routes ` with the appropriate arguments +3. Copy the server command output that best suits the Server OS and run it on the Server machine +4. On the Client, run `sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf` to import the configs into Wireguard +5. Confirm the handshake completed for both configs by running `sudo wg show` on the Client +6. (Optional) Add more servers and clients as needed with the `wiretap add` subcommand -While not ideal, Wiretap can still work with TCP instead of UDP. See the experimental [TCP Tunneling](#tcp-tunneling) section for a step-by-step guide. +See the [Usage section](#Usage) for more details. ## Installation -Grab a binary from the [releases](https://github.com/sandialabs/wiretap/releases) page. You may want two binaries if the OS/ARCH are different on the client and server machines. +No installation of Wiretap is required. Just grab a binary from the [releases](https://github.com/sandialabs/wiretap/releases) page. You may need two different binaries if the OS/ARCH are different on the client and server machines. If you want to compile it yourself or can't find the OS/ARCH you're looking for, install Go (>=1.20) from https://go.dev/dl/ and use the provided [Makefile](./src/Makefile). +## How it Works + +Feel free to skip this section, but understanding how Wiretap works at a high level is very helpful for troubleshooting when you run into issues or errors. Additionally, some of the documentation below assumes you've read this. + +> [!NOTE] +> This section is intended to provide an intuitive, working understanding of how Wiretap works, and may not be entirely technically accurate about implementation details. + + +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. + +Inside the relay tunnels, Wiretap establishes a second virtual End-to-End Encrypted (`EE2E`) network (`wiretap.conf`). This network is invisible to the real-world network. Each Server and Client gets its own unique internal IP addresses inside this network: `172.X.X.X` for IPv4, and `fd:XX::X` for IPv6. As the EE2E name suggests, each Client-Server pair within this virtual network become Wireguard peers, able to generate encrypted messages that only the other can decrypt. + +Wiretap Clients track which real-world IP ranges ("routes") have been assigned to each Server inside the relay network. When the Client machine generates a packet destined for a known Wiretap route, Wireguard encrypts it using the EE2E configuration associated with the Server assigned to that route. The encrypted packet (now a UDP datagram) gets marked with the E2EE 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 can decrypt. The Server receives the datagram, decrypts the relay encryption, identifies which of its peer servers in the relay network the EE2E datagram should be sent to next, and sends it off via the associated relay tunnel. + +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 sends the packet to the real-world IP address indicated in the packet header, and forwards any response packets back to the Client using the same process. + +Within the E2EE network (i.e., accessible only to Clients), Wiretap Servers expose an API to enable real-time configuration changes and to monitor the health of the Wiretap network. Each Server is assigned an additional unique IP (usually an IPv6 address) inside the E2EE network to enable the secure usage of this API. This IP is referred to as the "API address." + ## Usage +Wiretap provides the following subcommands, which are documented in this section: +* [configure](#Configure) +* [serve](#Serve) +* [add server](#Add-Server-(Optional)) +* [add client](#Add-Client-(Optional)) +* [expose](#Expose-(Port-Forwarding)) + +Get help for any subcommand by adding the `-h` flag to it. + +> [!TIP] +> Some deprecated and less-common flags are hidden from the standard help output. Add the `-H` flag as well to see them. + ### Configure
@@ -48,19 +100,21 @@ If you want to compile it yourself or can't find the OS/ARCH you're looking for, ![Wiretap Configure Arguments](media/Wiretap_Configure.svg)
-On the client machine, run Wiretap in configure mode to build a config +On the Client machine, run Wiretap's `configure` subcommand to generate starting config files: ```bash -./wiretap configure --endpoint --port --routes +./wiretap configure --endpoint --routes ``` -* `--endpoint` tells the Server how to connect to the Client's Relay interface (the E2EE interfaces already know how to talk to each other if the Relay interfaces are working) -* `--port` sets the listening port of the Client's Relay interface. It's set to the same port specified in the `--endpoint` socket argument by default. Note that the E2EE listening port (51821) does not need to be accessible to the Server -* `--routes` is the equivalent of WireGuard's AllowedIPs setting. This tells the Client to route traffic that matches these IP ranges through Wiretap. +* `--endpoint` tells the Server machine how to connect to the Client machine's Relay interface (the E2EE interfaces already know how to talk to each other if the Relay interfaces are working) +* `--routes` is the equivalent of WireGuard's `AllowedIPs` setting. This tells the Client to route traffic that matches these IP ranges through Wiretap. + +> [!IMPORTANT] +> By default the listening port will be configured to be the same as the port specified in the `--endpoint` socket. This can be overwritten using the `--port` argument. Following the example in the diagram: ```bash -./wiretap configure --endpoint 1.3.3.7:1337 --port 1337 --routes 10.0.0.0/24 +./wiretap configure --endpoint 1.3.3.7:1337 --routes 10.0.0.0/24 ``` ``` Configurations successfully generated. @@ -103,35 +157,38 @@ Config File: ./wiretap serve -f wiretap_server.conf ``` > [!NOTE] -> Wiretap uses 2 WireGuard interfaces per node in order to safely and scalably chain together servers. This means your client will bind to more than one port, but only the Relay Interface port needs to be accessible by the Server. See the [How It Works](#how-it-works) section for details. Use `--simple` in both the `config` command and the server's `serve` command if your setup requires a single interface on the client +> The 51821 ListenPort in `wiretap.conf` needs to be available for use on the Client, but does NOT need to be accessible to the Server over real-world networks. See the [How It Works](#how-it-works) section for details. Use `--simple` in both the `config` command and the Server's `serve` command if your setup requires a single interface on the Client -> [!NOTE] -> The wiretap_server.conf file uses a notation unique to Wiretap. It cannot be used to start a wiretap server with wg-quick or other tools. +Install the resulting `wiretap_relay.conf` and `wiretap.conf` configs files into WireGuard on the Client: -> [!TIP] -> You can modify the AllowedIPs in the wiretap.conf file any time after generating the config files, just reload the config file with `wg-quick down/up` after making the change. No changes are needed on the server to update them. +* If using a GUI, select the menu option similar to *Import Tunnel(s) From File* +* If you have `wg-quick` installed, run `sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf` -Install the resulting config either by copying and pasting the output or by importing the new `wiretap.conf` and `wiretap_relay.conf` files into WireGuard: +> [!TIP] +> You can modify the AllowedIPs in the `wiretap.conf` file any time after generating the config files, just reload the config file with `wg-quick down ./wiretap.conf && wg-quick up ./wiretap.conf` after making the change. No changes are needed on the server to update them. -* If using a GUI, select the menu option similar to *Import Tunnel(s) From File* -* If you have `wg-quick` installed, `sudo wg-quick up ./wiretap.conf` and `sudo wg-quick up ./wiretap_relay.conf` +> [!WARNING] +> In the default configuration, with the Client listening for an initial Server connection, the Server will still also listen on port 51820 so that other Servers can attach to it later. There is currently no way to change this when running the `configure` command, but when running `wiretap serve` you can manually change this in the `wiretap_server.conf` file, or using the `WIRETAP_RELAY_INTERFACE_PORT` environment variable. -Don't forget to disable or remove the tunnels when you're done (e.g., `sudo wg-quick down ./wiretap.conf` and `sudo wg-quick down ./wiretap_relay.conf`) +Don't forget to disable or remove the tunnels when you're done (e.g., `sudo wg-quick down ./wiretap.conf && sudo wg-quick down ./wiretap_relay.conf`) -### Deploy +### Serve -On the remote machine, upload the binary and then copy the command with the private and public keys to start Wiretap in server mode: +On the remote machine, upload the Wiretap binary and then copy the command with the private and public keys to start Wiretap in server mode: ```powershell $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="1.3.3.7:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve ``` There are two other ways to pass arguments to the server: -1. With a config file: `-f wiretap_server.conf` -2. The legacy method of passing command line arguments (`--endpoint 1.3.3.7:1337 ...`). Be aware that this method exposes arguments to other users on the system. A compromised private key can be used to connect to the client as a peer and/or decrypt traffic +1. With the generated server config file: `-f wiretap_server.conf` +2. The legacy method of passing command line arguments (`--endpoint 1.3.3.7:1337 ...`). Be aware that this method exposes the arguments to other users on the system. A compromised private key can be used to connect to the client as a peer and/or decrypt traffic + +> [!NOTE] +> The wiretap_server.conf file uses a notation unique to Wiretap. It cannot be used to start a server with `wg-quick` or other generic Wireguard tools. -Confirm that the relay interfaces on the client and server have successfully completed a handshake. The client should see successful handshakes in whatever WireGuard interface is running. If using the command-line tools, check with `wg show`. By default the E2EE handshake will not occur until the client sends data. +Confirm that the relay interfaces on the Client and Server have successfully completed a handshake. The Client should see successful handshakes in whatever WireGuard interface is running. If using the command-line tools, check with `sudo wg show`. By default the E2EE handshake will not occur until the Client sends data, so you may need to attempt to use the connection (e.g. `ping` an IP in the associated `--routes`) to trigger the handshake process. -Now the client should be able to interact with the `routes` specified in the `configure` command! +Now the Client should be able to interact with the `routes` specified in the `configure` command! ### Add Server (Optional) @@ -140,10 +197,10 @@ Now the client should be able to interact with the `routes` specified in the `co ![Wiretap Add Server Arguments](media/Wiretap_Add_Server.svg) -The `add server` subcommand is meant to extend the Wiretap network to reach new areas of a target network. One client and at least one server must be configured and deployed before adding another server. Servers can attach to any other server *or* the client itself. +The `add server` subcommand is meant to extend the Wiretap network to reach new areas of a target network. At least one Client and Server must be configured and successfully deployed (i.e., with `configure`) before adding another Server. Servers can attach to any other Server *or* the Client itself. > [!WARNING] -> All servers must be deployed *before* adding additional clients. Additionally, if a Wiretap server process exits or dies for any reason it will not remember any added clients when you restart it. +> Due to the way new Clients are added to existing networks, all Servers must be deployed *before* adding additional Clients. Added Clients won't be able to access Servers deployed after they were added. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. You can view the state of the network and see API addresses with `./wiretap status` @@ -173,9 +230,9 @@ You can view the state of the network and see API addresses with `./wiretap stat ╰─────────────────────╯ ``` -If you plan to attach a server directly to the client, the status command just confirms that everything is working as expected and the network layout is correct. If you want to attach a server to another server you must also specify the existing server's API address in your `add server` command with the `--server-address` argument; this API address must reference the same Wiretap server that the new server will connect to via the `--endpoint` socket. +If you plan to attach a Server directly to the Client, the status command just confirms that everything is working as expected and the network layout is correct. If you want to attach a new Server to an existing Server you must also specify the existing Server's API address in your `add server` command using the `--server-address` argument; this API address **must** reference the same existing Server that the new Server will connect to via the `--endpoint` socket or else the new connection will fail. -In the example, we will want to attach to the server with API address `::2`, which is listening on `10.0.0.2:51820`. This command will generate a configuration you can deploy to the new server (through environment variables or a config), just like with the `configure` command: +In this example, we will to the server with API address `::2`, which is listening on `10.0.0.2:51820`. This command will generate a configuration you can deploy to the new Server (through environment variables or a config), just like with the `configure` command: ```bash ./wiretap add server --server-address ::2 --endpoint 10.0.0.2:51820 --routes 10.0.1.0/24 @@ -211,9 +268,9 @@ POSIX Shell: WIRETAP_RELAY_INTERFACE_PRIVATEKEY=sLERnxT2+VdwwcJOTUHK5fa5sIN7oJ1 Config File: ./wiretap serve -f wiretap_server_1.conf ``` -The client's E2EE configuration will be modified to allow communication with the new server, so you need to reimport it. For example, `wg-quick down ./wiretap.conf` and `wg-quick up ./wiretap.conf`. If you are attaching a server directly to the client, the Relay interface will also need to be refreshed. +The Client's E2EE configuration (`wiretap.conf`) will be modified to allow communication with the new Server, so you need to reimport it. For example, `sudo wg-quick down ./wiretap.conf && sudo wg-quick up ./wiretap.conf`. If you are attaching a new Server directly to the Client, the Relay interface will also need to be refreshed in the same way. -Now you can use any of the server command options to deploy Wiretap to the new server. It will then connect to the already existing server. +Now you can use any of the `serve` command options to start Wiretap on the new Server. It will then join the Wiretap network by connecting to the existing Server. At this point the new routes should be usable! You can confirm that everything looks correct with `wiretap status`: @@ -252,7 +309,7 @@ At this point the new routes should be usable! You can confirm that everything l ╰─────────────────────╯ ``` -Now the client can reach `10.0.0.0/24` and `10.0.1.0/24`. From here you can attach more servers to any of the three nodes. +Now the Client can reach `10.0.0.0/24` and `10.0.1.0/24`. From here you can attach more Servers to any of the three existing nodes. ### Add Client (Optional) @@ -264,9 +321,9 @@ Now the client can reach `10.0.0.0/24` and `10.0.1.0/24`. From here you can atta The `add client` subcommand can be used to share access to the Wiretap network with others. > [!WARNING] -> All servers must be deployed *before* adding additional clients. Additionally, if a Wiretap server process exits or dies for any reason it will not remember any added clients when you restart it. +> All servers must be deployed *before* adding additional clients. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. -Adding a client is very similar to the other commands. It will generate a `wiretap.conf` and `wiretap_relay.conf` for sharing. Make sure that all of the first-hop servers (any server directly attached to the original client) can reach or be reached by the new client or else the new client won't have access to that chain of servers. Once you get the endpoint information from whoever will be running the new client run: +Adding a new Client is very similar to the other commands. It will generate a `wiretap.conf` and `wiretap_relay.conf` for sharing. Make sure that all of the first-hop Servers (any Server directly attached to the original Client) can reach or be reached by the new Client or else the new Client won't have access to that chain of Servers. Once you get the endpoint information from whoever will be running the new Client (the IP and port they will listen on), run: ```bash ./wiretap add client --endpoint 1.3.3.8:1337 --port 1337 @@ -309,26 +366,27 @@ Endpoint = 172.17.0.3:51821 ──────────────────────────────── ``` -Send these files and have the recipient import them into WireGuard to have access to everything in the Wiretap network! By default the routes (AllowedIPs) are copied over, but can be modified by the recipient as needed. +Send these files and have the recipient import them into WireGuard to have access to everything in the Wiretap network! By default the routes (AllowedIPs) are copied over to the new client configs, but can be modified by the recipient as needed. -### Port Forwarding +### Expose (Port Forwarding) > **Warning** -> Port forwarding exposes services on your local machine to the remote network, use with caution +> Port forwarding exposes ports and services on your local machine to the remote network, use with caution -You can expose a service on the client by using the `expose` subcommand. For example, to allow remote systems to access port 80/tcp on your local machine, you could run: +You can expose a port on the Client to IPs in Wiretap's `routes` list by using the `expose` subcommand. For example, to allow remote systems to access port 80/tcp on your local Client machine, you could run: ``` ./wiretap expose --local 80 --remote 8080 ``` -Now all Wiretap servers will be bound to port 8080/tcp and proxy connections to your services on port 80/tcp. By default this uses IPv6, so make sure any listening services support IPv6 as well. +Now all Wiretap Servers will be bound to listen on port 8080/tcp and proxy connections to your service on port 80/tcp. By default this uses IPv6, so make sure any exposed services listening on the Client support IPv6 as well. + To configure Wiretap to only use IPv4, use the `configure` subcommand's `--disable-ipv6` option. > [!WARNING] > If a Wiretap server process exits or dies for any reason it will not remember ports it was previously exposing. You will need to re-expose any ports you configured with this command. -To dynamically forward all ports using SOCKS5: +To dynamically expose all ports on the Client using SOCKS5: ``` ./wiretap expose --dynamic --remote 8080 @@ -418,192 +476,10 @@ Use "wiretap [command] --help" for more information about a command. ## Demo -The demo has four hosts and three networks for testing multi-hop/nested tunnels, but only the first target host is reached in the examples below. - -``` -┌──────────┐ -│ client │ -│ │ -│ 10.1.0.2 ├┬───────────────────────┐ -│ fd:1::2 --- │ -└──────────┼│ │ - ││ exposed network │ - ││ 10.1.0.0/16,fd:1::/64 │ -┌──────────┼│ │ -│ 10.1.0.3 --- │ -│ fd:1::3 ├┴───────────────────────┘ -│ │ -│ server │ -│ │ -│ 10.2.0.3 ├┬───────────────────────┐ -│ fd:2::3 --- | -└──────────┼│ │ - ││ target network │ - ││ 10.2.0.0/16,fd:2::/64 │ -┌──────────┼│ │ -│ 10.2.0.4 --- | -│ fd:2::4 ├┴───────────────────────┘ -│ │ -│ target │ -│ │ -│ 10.3.0.4 ├┬───────────────────────┐ -│ fd:3::4 --- | -└──────────┼│ │ - ││ target2 network │ - ││ 10.3.0.0/16,fd:3::/64 │ -┌──────────┼│ │ -│ 10.3.0.5 --- | -│ fd:3::5 ├┴───────────────────────┘ -│ │ -│ target2 │ -└──────────┘ -``` - -### Video - -
- -https://user-images.githubusercontent.com/26662746/230233549-964a0c91-9c9f-4bd8-b13e-36af08ff8425.mp4 -
- -### Step-By-Step - -You have unprivileged access to the server host and want to reach the target host from the client host using Wiretap. - -#### Setup - -Clone this repo. - -Start the demo containers with: -```bash -docker compose up --build -``` - -Open new tabs for interactive sessions with the client and server machines: -```bash -docker exec -it wiretap-client-1 bash -``` -```bash -docker exec -it wiretap-server-1 bash -``` - -#### Observe Network Limitations - -The target network, and therefore the target host, is unreachable from the client machine. Both the server and target hosts are running a web service on port 80, so try interacting with each of the services from each of the hosts: - -Accessing the server's web service from the client should work: -```bash -client$ curl http://10.1.0.3 -``` - -Accessing the target web service from the client should not work, but doing the same thing from the server machine will: - -```bash -# fails -client$ curl http://10.2.0.4 -``` -```bash -server$ curl http://10.2.0.4 -``` - -#### Configure - -Configure Wiretap from the client machine. Remember, `--endpoint` is how the server machine should reach the client (IP:port) and `--routes` determines which traffic is routed through Wiretap. - -* `--endpoint` needs to be the client address and listening port: `10.1.0.2:51820` -* If no `--port` is specified, the client config will use the same port specified in the `endpoint` argument as the listening port. In this example, that would be 51820. -* `--routes` needs to be the subnet of the target network: `10.2.0.0/16`. But there is also an IPv6 subnet, so we should also put `fd:2::/64`. If you just wanted to route traffic to the target host, you could put `10.2.0.4/32` here instead - -```bash -./wiretap configure --endpoint 10.1.0.2:51820 --routes 10.2.0.0/16,fd:2::/64 -``` - -Install the newly created WireGuard configs with: - -```bash -wg-quick up ./wiretap_relay.conf -wg-quick up ./wiretap.conf -``` - -Copy and paste the Wiretap arguments printed by the configure command into the server machine prompt. It should look like this: - -```bash -WIRETAP_RELAY_INTERFACE_PRIVATEKEY= WIRETAP_RELAY_PEER_PUBLICKEY= WIRETAP_RELAY_PEER_ENDPOINT=10.1.0.2:51820 WIRETAP_E2EE_INTERFACE_PRIVATEKEY= WIRETAP_E2EE_PEER_PUBLICKEY= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve -``` - -#### Test +Please see the [Demo page in the Wiki](https://github.com/sandialabs/wiretap/wiki/Demo) for instructions on setting up the demo Docker environment. -The WireGuard handshake should be complete. Confirm with: - -```bash -wg show -``` - -If the handshake was successful the client should be able to reach the target network transparently. Confirm by running the same test that failed before: - -```bash -client$ curl http://10.2.0.4 -``` - -That's it! Try scanning, pinging, and anything else you can think of (please submit an issue if you think something should work but doesn't!). Here are a few ideas: -- HTTP - - `curl http://10.2.0.4` - - `curl http://[fd:2::4]` -- Nmap - - `nmap 10.2.0.4 -v` - - `nmap -6 fd:2::4 -v` -- ICMP - - `ping 10.2.0.4` - - `ping fd:2::4` -- UDP - - `nmap -sU 10.2.0.4 -v` - - `nmap -sU -6 fd:2::4 -v` - -#### Exercise - -Try to reach the second target by adding another server! You should be able to successfully run `curl http://10.3.0.5` from the client host if performed correctly. The `status` command should output something similar to: - -``` -╭────────────────────────╮ -│ Wiretap Network Status │ -╰────────────┬───────────╯ - │ - ╭──────────┴──────────╮ - │client │ - │ │ - │ relay: Ta75SvIb... │ - │ e2ee: cXddDGWC... │ - │ │ - ╰──────────┬──────────╯ - │ - ╭──────────┴──────────╮ - │server │ - │ relay: kMj7HwfY... │ - │ e2ee: 3ipWthpJ... │ - │ │ - │ api: ::2 │ - │ routes: 10.2.0.0/16 │ - ╰──────────┬──────────╯ - │ - ╭──────────┴──────────╮ - │server │ - │ relay: GMkUzfDy... │ - │ e2ee: YOVI9nOv... │ - │ │ - │ api: ::3 │ - │ routes: 10.3.0.0/16 │ - ╰─────────────────────╯ -``` - - -#### Teardown - -To bring down the WireGuard interfaces on the client machine, run: - -```bash -wg-quick down ./wiretap_relay.conf -wg-quick down ./wiretap.conf -``` +> [!TIP] +> The interactive demo environment is a great way to get your feet wet testing out how Wiretap works. It provides an ideal network environment, ensuring you can focus on learning how to use Wiretap as intended without getting stuck troubleshooting weird network errors that you often encounter in the real world. ## Experimental From b010ca00420d8ebbfd0e28879ba8ac9de8d2cd90 Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 11:22:03 -0600 Subject: [PATCH 04/22] Improved diagram --- media/Wiretap_E2EE.drawio | 213 ++++++++++++++++++++++---------------- media/Wiretap_E2EE.svg | 21 +--- 2 files changed, 130 insertions(+), 104 deletions(-) diff --git a/media/Wiretap_E2EE.drawio b/media/Wiretap_E2EE.drawio index 1224a19..6ce1ea2 100644 --- a/media/Wiretap_E2EE.drawio +++ b/media/Wiretap_E2EE.drawio @@ -1,58 +1,57 @@ - + - + - + + + + + + + + + + - + - + - + - - + + - + - - - - - - - - - - + - + - + - - - + + - + - + @@ -60,107 +59,147 @@ - - + + - + - + - - - - - + + - - - - + - - - - - + + - + - + - + + - - - - - - - - - - - + + - - + + - - - - - + + - - - - + - + - + - + - + - + - - + + + + + + + + + + + + + + - + - - + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + - - + + - + - - + + - - + + + + + + + + + + + + + + + + + + + + diff --git a/media/Wiretap_E2EE.svg b/media/Wiretap_E2EE.svg index 2cf8ee9..dd74697 100644 --- a/media/Wiretap_E2EE.svg +++ b/media/Wiretap_E2EE.svg @@ -1,17 +1,4 @@ - -ClientClient -Server 1Server 1 - -WireGuard End-to-End Encrypted InterfaceWireGuard End-to-End Encrypted Inter... -WireGuard RelayInterfaceWireGuard Relay...UnencryptedEnd-To-End EncryptedRelayUnencrypted... -Server 2Server 2Text is not SVG - cannot display \ No newline at end of file + + + +

Client

Server 1


WireGuard End-to-End Encrypted Interface

WireGuard Relay
Interface
Unencrypted
End-To-End Encrypted
Relay Encrypted

Server 2
 \ No newline at end of file From ec3015e8f6f9983be10b8714a3055fdc7645d3ed Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 11:22:38 -0600 Subject: [PATCH 05/22] Increased all heading levels --- README.md | 120 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 63 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index c47b2cf..108dc9d 100644 --- a/README.md +++ b/README.md @@ -12,74 +12,74 @@ In this diagram, the Client has generated and installed WireGuard configuration ![Wiretap Diagram](media/Wiretap_Animated.svg) -## Terminology and Requirements +# Terminology and Requirements -A Wiretap Server is any machine where a Wiretap binary is running the `serve` subcommand. Servers generate and receive network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." +A Wiretap Server is any machine where a Wiretap binary is running the `serve` subcommand. Servers generate and receive network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." -A Wiretap Client is any machine running the Wireguard configurations necessary to send network traffic through a Wiretap server. It functions much like a client in a VPN connection. +A Wiretap Client is any machine running the Wireguard configurations necessary to send network traffic through a Wiretap Server. It functions much like a client in a VPN connection. > [!IMPORTANT] -> Unlike the typical use of "client" and "server" terms in networking, Wiretap's Client and Server terms have nothing to do with which machine listens for or initiates the initial connection. +> Unlike the typical use of "client" and "server" terms in networking, Wiretap's Client and Server terms have nothing to do with which machine listens for or initiates the initial connection. -### Client System Requirements +## Client System Requirements * WireGuard - https://www.wireguard.com/install/ * Privileged access necessary to configure WireGuard -### Server System Requirements +## Server System Requirements * Ability to get the Wiretap binary onto the Server system, and run it -### Environment Requirements +## Environment Requirements -* Bidirectional UDP communication between Server and Client on one port. Any firewalls between them must allow at least one machine to initiate the UDP connection to the other. +* Bidirectional UDP communication between Server and Client on one port. Any firewalls between them must allow at least one machine to initiate the UDP connection to the other. * The machine receiving the initial connection (the Client by default) must be able to listen for UDP connections on a port that the initiating machine can connect to. > [!NOTE] -> By default the Server initiates the handshake to the Client because the Server is more likely to have outbound UDP allowed through a firewall than inbound UDP, but the reverse is easily configurable. +> By default the Server initiates the handshake to the Client because the Server is more likely to have outbound UDP allowed through a firewall than inbound UDP, but the reverse is easily configurable. While not ideal, Wiretap can still work with TCP instead of UDP. See the experimental [TCP Tunneling](#tcp-tunneling) section for more info. -## Quick Start +# Quick Start 1. Download binaries from the [releases](https://github.com/sandialabs/wiretap/releases) page, one for your Client machine and one for your Server machine (if different os/arch). Copy the Wiretap binary onto the server -2. On the Client, run `./wiretap configure --endpoint --routes ` with the appropriate arguments +2. On the Client, run `./wiretap configure --endpoint : --routes ` with the appropriate arguments 3. Copy the server command output that best suits the Server OS and run it on the Server machine 4. On the Client, run `sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf` to import the configs into Wireguard 5. Confirm the handshake completed for both configs by running `sudo wg show` on the Client 6. (Optional) Add more servers and clients as needed with the `wiretap add` subcommand -See the [Usage section](#Usage) for more details. +See the [Usage section](#Usage) for more details. -## Installation +# Installation No installation of Wiretap is required. Just grab a binary from the [releases](https://github.com/sandialabs/wiretap/releases) page. You may need two different binaries if the OS/ARCH are different on the client and server machines. If you want to compile it yourself or can't find the OS/ARCH you're looking for, install Go (>=1.20) from https://go.dev/dl/ and use the provided [Makefile](./src/Makefile). -## How it Works +# How it Works -Feel free to skip this section, but understanding how Wiretap works at a high level is very helpful for troubleshooting when you run into issues or errors. Additionally, some of the documentation below assumes you've read this. +Feel free to skip this section, but understanding how Wiretap works at a high level is very helpful for troubleshooting when you run into issues or errors. Additionally, some of the documentation below assumes you've read this. > [!NOTE] -> This section is intended to provide an intuitive, working understanding of how Wiretap works, and may not be entirely technically accurate about implementation details. +> This section is intended to provide an intuitive, working understanding of how Wiretap works, and may not be entirely technically accurate about implementation details. -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. +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. -Inside the relay tunnels, Wiretap establishes a second virtual End-to-End Encrypted (`EE2E`) network (`wiretap.conf`). This network is invisible to the real-world network. Each Server and Client gets its own unique internal IP addresses inside this network: `172.X.X.X` for IPv4, and `fd:XX::X` for IPv6. As the EE2E name suggests, each Client-Server pair within this virtual network become Wireguard peers, able to generate encrypted messages that only the other can decrypt. +Inside the relay tunnels, Wiretap establishes a second virtual End-to-End Encrypted (`EE2E`) network (`wiretap.conf`). This network is invisible to the real-world network. Each Server and Client gets its own unique internal IP addresses inside this network: `172.X.X.X` for IPv4, and `fd:XX::X` for IPv6. As the EE2E name suggests, each Client-Server pair within this virtual network become Wireguard peers, able to generate encrypted messages that only the other can decrypt. -Wiretap Clients track which real-world IP ranges ("routes") have been assigned to each Server inside the relay network. When the Client machine generates a packet destined for a known Wiretap route, Wireguard encrypts it using the EE2E configuration associated with the Server assigned to that route. The encrypted packet (now a UDP datagram) gets marked with the E2EE IP address of the assigned server as its destination. +Wiretap Clients track which real-world IP ranges ("routes") have been assigned to each Server inside the relay network. When the Client machine generates a packet destined for a known Wiretap route, Wireguard encrypts it using the EE2E configuration associated with the Server assigned to that route. The encrypted packet (now a UDP datagram) gets marked with the E2EE 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 can decrypt. The Server receives the datagram, decrypts the relay encryption, identifies which of its peer servers in the relay network the EE2E datagram should be sent to next, and sends it off via the associated relay tunnel. +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 can decrypt. The Server receives the datagram, decrypts the relay encryption, identifies which of its peer servers in the relay network the EE2E datagram should be sent to next, and sends it off via the associated relay tunnel. -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 sends the packet to the real-world IP address indicated in the packet header, and forwards any response packets back to the Client using the same process. +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 sends the packet to the real-world IP address indicated in the packet header, and forwards any response packets back to the Client using the same process. Within the E2EE network (i.e., accessible only to Clients), Wiretap Servers expose an API to enable real-time configuration changes and to monitor the health of the Wiretap network. Each Server is assigned an additional unique IP (usually an IPv6 address) inside the E2EE network to enable the secure usage of this API. This IP is referred to as the "API address." -## Usage +# Usage Wiretap provides the following subcommands, which are documented in this section: * [configure](#Configure) @@ -88,12 +88,12 @@ Wiretap provides the following subcommands, which are documented in this section * [add client](#Add-Client-(Optional)) * [expose](#Expose-(Port-Forwarding)) -Get help for any subcommand by adding the `-h` flag to it. +Get help for any subcommand by adding the `-h` flag to it. > [!TIP] -> Some deprecated and less-common flags are hidden from the standard help output. Add the `-H` flag as well to see them. +> Some deprecated and less-common flags are hidden from the standard help output. Add the `-H` flag as well to see them. -### Configure +## Configure
@@ -103,19 +103,24 @@ Get help for any subcommand by adding the `-h` flag to it. On the Client machine, run Wiretap's `configure` subcommand to generate starting config files: ```bash -./wiretap configure --endpoint --routes +./wiretap configure --endpoint : --routes ``` * `--endpoint` tells the Server machine how to connect to the Client machine's Relay interface (the E2EE interfaces already know how to talk to each other if the Relay interfaces are working) * `--routes` is the equivalent of WireGuard's `AllowedIPs` setting. This tells the Client to route traffic that matches these IP ranges through Wiretap. > [!IMPORTANT] -> By default the listening port will be configured to be the same as the port specified in the `--endpoint` socket. This can be overwritten using the `--port` argument. +> By default the listening port will be configured to be the same as the port specified in the `--endpoint` IP:port. This can be overwritten using the `--port` argument. Following the example in the diagram: ```bash ./wiretap configure --endpoint 1.3.3.7:1337 --routes 10.0.0.0/24 ``` + +
+ +Output + ``` Configurations successfully generated. Import the two configs into WireGuard locally and pass the arguments below to Wiretap on the remote machine. @@ -155,6 +160,7 @@ POSIX Shell: WIRETAP_RELAY_INTERFACE_PRIVATEKEY=WDH8F6rSUZDyQFfEsRjWLCnapU254qr PowerShell: $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_INTERFACE_PORT="51820"; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="1.3.3.7:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve Config File: ./wiretap serve -f wiretap_server.conf ``` +
> [!NOTE] > The 51821 ListenPort in `wiretap.conf` needs to be available for use on the Client, but does NOT need to be accessible to the Server over real-world networks. See the [How It Works](#how-it-works) section for details. Use `--simple` in both the `config` command and the Server's `serve` command if your setup requires a single interface on the Client @@ -165,14 +171,14 @@ Install the resulting `wiretap_relay.conf` and `wiretap.conf` configs files into * If you have `wg-quick` installed, run `sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf` > [!TIP] -> You can modify the AllowedIPs in the `wiretap.conf` file any time after generating the config files, just reload the config file with `wg-quick down ./wiretap.conf && wg-quick up ./wiretap.conf` after making the change. No changes are needed on the server to update them. +> You can modify the AllowedIPs in the `wiretap.conf` file any time after generating the config files, just reload the config file with `wg-quick down ./wiretap.conf && wg-quick up ./wiretap.conf` after making the change. No changes are needed on the server to update them. > [!WARNING] -> In the default configuration, with the Client listening for an initial Server connection, the Server will still also listen on port 51820 so that other Servers can attach to it later. There is currently no way to change this when running the `configure` command, but when running `wiretap serve` you can manually change this in the `wiretap_server.conf` file, or using the `WIRETAP_RELAY_INTERFACE_PORT` environment variable. +> In the default configuration, with the Client listening for an initial Server connection, the Server will still also listen on port 51820 so that other Servers can attach to it later. There is currently no way to change this when running the `configure` command, but when running `wiretap serve` you can manually change this in the `wiretap_server.conf` file, or using the `WIRETAP_RELAY_INTERFACE_PORT` environment variable. Don't forget to disable or remove the tunnels when you're done (e.g., `sudo wg-quick down ./wiretap.conf && sudo wg-quick down ./wiretap_relay.conf`) -### Serve +## Serve On the remote machine, upload the Wiretap binary and then copy the command with the private and public keys to start Wiretap in server mode: ```powershell @@ -184,13 +190,13 @@ There are two other ways to pass arguments to the server: 2. The legacy method of passing command line arguments (`--endpoint 1.3.3.7:1337 ...`). Be aware that this method exposes the arguments to other users on the system. A compromised private key can be used to connect to the client as a peer and/or decrypt traffic > [!NOTE] -> The wiretap_server.conf file uses a notation unique to Wiretap. It cannot be used to start a server with `wg-quick` or other generic Wireguard tools. +> The wiretap_server.conf file uses a notation unique to Wiretap. It cannot be used to start a server with `wg-quick` or other generic Wireguard tools. -Confirm that the relay interfaces on the Client and Server have successfully completed a handshake. The Client should see successful handshakes in whatever WireGuard interface is running. If using the command-line tools, check with `sudo wg show`. By default the E2EE handshake will not occur until the Client sends data, so you may need to attempt to use the connection (e.g. `ping` an IP in the associated `--routes`) to trigger the handshake process. +Confirm that the relay interfaces on the Client and Server have successfully completed a handshake. The Client should see successful handshakes in whatever WireGuard interface is running. If using the command-line tools, check with `sudo wg show`. By default the E2EE handshake will not occur until the Client sends data, so you may need to attempt to use the connection (e.g. `ping` an IP in the associated `--routes`) to trigger the handshake process. Now the Client should be able to interact with the `routes` specified in the `configure` command! -### Add Server (Optional) +## Add Server (Optional)
@@ -200,7 +206,7 @@ Now the Client should be able to interact with the `routes` specified in the `co The `add server` subcommand is meant to extend the Wiretap network to reach new areas of a target network. At least one Client and Server must be configured and successfully deployed (i.e., with `configure`) before adding another Server. Servers can attach to any other Server *or* the Client itself. > [!WARNING] -> Due to the way new Clients are added to existing networks, all Servers must be deployed *before* adding additional Clients. Added Clients won't be able to access Servers deployed after they were added. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. +> Due to the way new Clients are added to existing networks, all Servers must be deployed *before* adding additional Clients. Added Clients won't be able to access Servers deployed after they were added. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. You can view the state of the network and see API addresses with `./wiretap status` @@ -230,7 +236,7 @@ You can view the state of the network and see API addresses with `./wiretap stat ╰─────────────────────╯ ``` -If you plan to attach a Server directly to the Client, the status command just confirms that everything is working as expected and the network layout is correct. If you want to attach a new Server to an existing Server you must also specify the existing Server's API address in your `add server` command using the `--server-address` argument; this API address **must** reference the same existing Server that the new Server will connect to via the `--endpoint` socket or else the new connection will fail. +If you plan to attach a Server directly to the Client, the status command just confirms that everything is working as expected and the network layout is correct. If you want to attach a new Server to an existing Server you must also specify the existing Server's API address in your `add server` command using the `--server-address` argument; this API address **must** reference the same existing Server that the new Server will connect to via the `--endpoint` IP:port or else the new connection will fail. In this example, we will to the server with API address `::2`, which is listening on `10.0.0.2:51820`. This command will generate a configuration you can deploy to the new Server (through environment variables or a config), just like with the `configure` command: @@ -268,9 +274,9 @@ POSIX Shell: WIRETAP_RELAY_INTERFACE_PRIVATEKEY=sLERnxT2+VdwwcJOTUHK5fa5sIN7oJ1 Config File: ./wiretap serve -f wiretap_server_1.conf ``` -The Client's E2EE configuration (`wiretap.conf`) will be modified to allow communication with the new Server, so you need to reimport it. For example, `sudo wg-quick down ./wiretap.conf && sudo wg-quick up ./wiretap.conf`. If you are attaching a new Server directly to the Client, the Relay interface will also need to be refreshed in the same way. +The Client's E2EE configuration (`wiretap.conf`) will be modified to allow communication with the new Server, so you need to reimport it. For example, `sudo wg-quick down ./wiretap.conf && sudo wg-quick up ./wiretap.conf`. If you are attaching a new Server directly to the Client, the Relay interface will also need to be refreshed in the same way. -Now you can use any of the `serve` command options to start Wiretap on the new Server. It will then join the Wiretap network by connecting to the existing Server. +Now you can use any of the `serve` command options to start Wiretap on the new Server. It will then join the Wiretap network by connecting to the existing Server. At this point the new routes should be usable! You can confirm that everything looks correct with `wiretap status`: @@ -311,7 +317,7 @@ At this point the new routes should be usable! You can confirm that everything l Now the Client can reach `10.0.0.0/24` and `10.0.1.0/24`. From here you can attach more Servers to any of the three existing nodes. -### Add Client (Optional) +## Add Client (Optional)
@@ -321,9 +327,9 @@ Now the Client can reach `10.0.0.0/24` and `10.0.1.0/24`. From here you can atta The `add client` subcommand can be used to share access to the Wiretap network with others. > [!WARNING] -> All servers must be deployed *before* adding additional clients. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. +> All servers must be deployed *before* adding additional clients. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. -Adding a new Client is very similar to the other commands. It will generate a `wiretap.conf` and `wiretap_relay.conf` for sharing. Make sure that all of the first-hop Servers (any Server directly attached to the original Client) can reach or be reached by the new Client or else the new Client won't have access to that chain of Servers. Once you get the endpoint information from whoever will be running the new Client (the IP and port they will listen on), run: +Adding a new Client is very similar to the other commands. It will generate a `wiretap.conf` and `wiretap_relay.conf` for sharing. Make sure that all of the first-hop Servers (any Server directly attached to the original Client) can reach or be reached by the new Client or else the new Client won't have access to that chain of Servers. Once you get the endpoint information from whoever will be running the new Client (the IP and port they will listen on), run: ```bash ./wiretap add client --endpoint 1.3.3.8:1337 --port 1337 @@ -366,9 +372,9 @@ Endpoint = 172.17.0.3:51821 ──────────────────────────────── ``` -Send these files and have the recipient import them into WireGuard to have access to everything in the Wiretap network! By default the routes (AllowedIPs) are copied over to the new client configs, but can be modified by the recipient as needed. +Send these files and have the recipient import them into WireGuard to have access to everything in the Wiretap network! By default the routes (AllowedIPs) are copied over to the new client configs, but can be modified by the recipient as needed. -### Expose (Port Forwarding) +## Expose (Port Forwarding) > **Warning** > Port forwarding exposes ports and services on your local machine to the remote network, use with caution @@ -379,9 +385,9 @@ You can expose a port on the Client to IPs in Wiretap's `routes` list by using t ./wiretap expose --local 80 --remote 8080 ``` -Now all Wiretap Servers will be bound to listen on port 8080/tcp and proxy connections to your service on port 80/tcp. By default this uses IPv6, so make sure any exposed services listening on the Client support IPv6 as well. +Now all Wiretap Servers will be bound to listen on port 8080/tcp and proxy connections to your service on port 80/tcp. By default this uses IPv6, so make sure any exposed services listening on the Client support IPv6 as well. -To configure Wiretap to only use IPv4, use the `configure` subcommand's `--disable-ipv6` option. +To configure Wiretap to only use IPv4, use the `configure` subcommand's `--disable-ipv6` option. > [!WARNING] > If a Wiretap server process exits or dies for any reason it will not remember ports it was previously exposing. You will need to re-expose any ports you configured with this command. @@ -400,11 +406,11 @@ curl -x socks5://:8080 http://:1337 The destination IP will be rewritten by the server so you can put any address. -#### List +### List Use `./wiretap expose list` to see all forwarding rules currently configured. -#### Remove +### Remove Use `./wiretap expose remove` with the same arguments used in `expose` to delete a rule. For example, to remove the SOCKS5 example above: @@ -412,7 +418,7 @@ Use `./wiretap expose remove` with the same arguments used in `expose` to delete ./wiretap expose remove --dynamic --remote 8080 ``` -## How It Works +# How It Works A traditional VPN can't be installed by unprivileged users because VPNs rely on dangerous operations like changing network routes and working with raw packets. @@ -425,7 +431,7 @@ To build secure and scalable tunnels across multiple hops, each node in the Wire ![Wiretap E2EE Architecture](media/Wiretap_E2EE.svg)
-## Help +# Help ```bash ./wiretap --help --show-hidden @@ -452,7 +458,7 @@ Flags: Use "wiretap [command] --help" for more information about a command. ``` -## Features +# Features * Network - IPv4 @@ -474,16 +480,16 @@ Use "wiretap [command] --help" for more information about a command. - Chain servers together to tunnel traffic through an arbitrary number of machines - Add clients after deployment for multi-user support -## Demo +# Demo -Please see the [Demo page in the Wiki](https://github.com/sandialabs/wiretap/wiki/Demo) for instructions on setting up the demo Docker environment. +Please see the [Demo page in the Wiki](https://github.com/sandialabs/wiretap/wiki/Demo) for instructions on setting up the demo Docker environment. > [!TIP] -> The interactive demo environment is a great way to get your feet wet testing out how Wiretap works. It provides an ideal network environment, ensuring you can focus on learning how to use Wiretap as intended without getting stuck troubleshooting weird network errors that you often encounter in the real world. +> The interactive demo environment is a great way to get your feet wet testing out how Wiretap works. It provides an ideal network environment, ensuring you can focus on learning how to use Wiretap as intended without getting stuck troubleshooting weird network errors that you often encounter in the real world. -## Experimental +# Experimental -### TCP Tunneling +## TCP Tunneling > [!WARNING] > Performance will suffer, only use TCP Tunneling as a last resort @@ -501,7 +507,7 @@ Run `chisel server` on the wiretap client system, specifying a TCP port you can ``` > [!Note] -> In this example we run the `chisel server ...` command on the Wiretap *client*, and `chisel client ...` command on a Wiretap *server*. This is because the chisel "client" always tries to reach out and connect to the chisel "server," whereas Wiretap clients and servers are defined by their functionality since either can initiate the connection. +> In this example we run the `chisel server ...` command on the Wiretap *client*, and `chisel client ...` command on a Wiretap *server*. This is because the chisel "client" always tries to reach out and connect to the chisel "server," whereas Wiretap clients and servers are defined by their functionality since either can initiate the connection. In this example, we're connecting chisel to the listener on 8080 (on the wiretap client) and forwarding 61820/udp from the Wiretap server to 51820 (any interface) on the Wiretap client: ```bash @@ -516,7 +522,7 @@ Finally, run Wiretap on the remote server system with the forwarded localhost po WIRETAP_RELAY_INTERFACE_PRIVATEKEY= WIRETAP_RELAY_PEER_PUBLICKEY= WIRETAP_E2EE_INTERFACE_PRIVATEKEY= WIRETAP_E2EE_PEER_PUBLICKEY= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve --endpoint localhost:61820 ``` -### Add Clients To Any Server +## Add Clients To Any Server > [!NOTE] > Clients added to arbitrary servers do not currently have the same capabilities as clients added to first-hop servers (the default) @@ -542,4 +548,4 @@ In this example, a new client (C2) is added to the second server in the right br └──────┘ ``` -You may also need to manually edit the resulting `wiretap.conf` for the new client to remove any `AllowedIPs` entries that already exist in the new client's host routing table. If the server that the client is attaching to has a route for 10.2.0.0/16, but the Client already has that route (because that's where it lives), then remove the `10.2.0.0/16` entry from the `wiretap.conf` file before importing into WireGuard. Leave the API address and any other routes you wish to access. +You may also need to manually edit the resulting `wiretap.conf` for the new client to remove any `AllowedIPs` entries that already exist in the new client's host routing table. If the server that the client is attaching to has a route for 10.2.0.0/16, but the Client already has that route (because that's where it lives), then remove the `10.2.0.0/16` entry from the `wiretap.conf` file before importing into WireGuard. Leave the API address and any other routes you wish to access. From 18098146143225c5883ac778b410eaf805b01d2c Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 11:32:48 -0600 Subject: [PATCH 06/22] Tweaked expansion block formatting --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 108dc9d..1a68421 100644 --- a/README.md +++ b/README.md @@ -117,9 +117,11 @@ Following the example in the diagram: ./wiretap configure --endpoint 1.3.3.7:1337 --routes 10.0.0.0/24 ``` +--- +
-Output +Click to view output ``` Configurations successfully generated. @@ -162,6 +164,8 @@ Config File: ./wiretap serve -f wiretap_server.conf ```
+--- + > [!NOTE] > The 51821 ListenPort in `wiretap.conf` needs to be available for use on the Client, but does NOT need to be accessible to the Server over real-world networks. See the [How It Works](#how-it-works) section for details. Use `--simple` in both the `config` command and the Server's `serve` command if your setup requires a single interface on the Client @@ -180,9 +184,9 @@ Don't forget to disable or remove the tunnels when you're done (e.g., `sudo wg-q ## Serve -On the remote machine, upload the Wiretap binary and then copy the command with the private and public keys to start Wiretap in server mode: +On the remote machine, upload the Wiretap binary and then run one of the commands from the output of `configure` to start Wiretap in server mode: ```powershell -$env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="1.3.3.7:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve +$env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_INTERFACE_PORT="51820"; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="1.3.3.7:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve ``` There are two other ways to pass arguments to the server: @@ -238,7 +242,7 @@ You can view the state of the network and see API addresses with `./wiretap stat If you plan to attach a Server directly to the Client, the status command just confirms that everything is working as expected and the network layout is correct. If you want to attach a new Server to an existing Server you must also specify the existing Server's API address in your `add server` command using the `--server-address` argument; this API address **must** reference the same existing Server that the new Server will connect to via the `--endpoint` IP:port or else the new connection will fail. -In this example, we will to the server with API address `::2`, which is listening on `10.0.0.2:51820`. This command will generate a configuration you can deploy to the new Server (through environment variables or a config), just like with the `configure` command: +In this example, we will to the server with API address `::2`, which is listening on `10.0.0.2:51820`. This command will generate a configuration you can deploy to the new Server (through environment variables or a config file), just like with the `configure` command: ```bash ./wiretap add server --server-address ::2 --endpoint 10.0.0.2:51820 --routes 10.0.1.0/24 From da48160bbae8160dafdf94150440a33710f50756 Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 11:39:53 -0600 Subject: [PATCH 07/22] move Help into Usage; more collapsed content --- README.md | 93 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 57 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 1a68421..f601326 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ In this diagram, the Client has generated and installed WireGuard configuration # Terminology and Requirements -A Wiretap Server is any machine where a Wiretap binary is running the `serve` subcommand. Servers generate and receive network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." +A Wiretap Server is any machine where a Wiretap binary is running the `serve` command. Servers generate and receive network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." A Wiretap Client is any machine running the Wireguard configurations necessary to send network traffic through a Wiretap Server. It functions much like a client in a VPN connection. @@ -49,7 +49,7 @@ While not ideal, Wiretap can still work with TCP instead of UDP. See the experim 3. Copy the server command output that best suits the Server OS and run it on the Server machine 4. On the Client, run `sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf` to import the configs into Wireguard 5. Confirm the handshake completed for both configs by running `sudo wg show` on the Client -6. (Optional) Add more servers and clients as needed with the `wiretap add` subcommand +6. (Optional) Add more servers and clients as needed with the `wiretap add` command See the [Usage section](#Usage) for more details. @@ -81,14 +81,39 @@ Within the E2EE network (i.e., accessible only to Clients), Wiretap Servers expo # Usage -Wiretap provides the following subcommands, which are documented in this section: +```bash +./wiretap --help --show-hidden +``` +``` +Usage: + wiretap [flags] + wiretap [command] + +Available Commands: + add Add peer to wiretap + configure Build wireguard config + expose Expose local services to servers + help Help about any command + ping Ping wiretap server API + serve Listen and proxy traffic into target network + status Show peer layout + +Flags: + -h, --help help for wiretap + -H, --show-hidden show hidden flag options + -v, --version version for wiretap + +Use "wiretap [command] --help" for more information about a command. +``` + +The following commands are documented in this section: * [configure](#Configure) * [serve](#Serve) * [add server](#Add-Server-(Optional)) * [add client](#Add-Client-(Optional)) * [expose](#Expose-(Port-Forwarding)) -Get help for any subcommand by adding the `-h` flag to it. +Get help for any command by adding the `-h` flag to it. > [!TIP] > Some deprecated and less-common flags are hidden from the standard help output. Add the `-H` flag as well to see them. @@ -100,7 +125,7 @@ Get help for any subcommand by adding the `-h` flag to it. ![Wiretap Configure Arguments](media/Wiretap_Configure.svg)
-On the Client machine, run Wiretap's `configure` subcommand to generate starting config files: +On the Client machine, run Wiretap's `configure` command to generate starting config files: ```bash ./wiretap configure --endpoint : --routes @@ -207,7 +232,7 @@ Now the Client should be able to interact with the `routes` specified in the `co ![Wiretap Add Server Arguments](media/Wiretap_Add_Server.svg)
-The `add server` subcommand is meant to extend the Wiretap network to reach new areas of a target network. At least one Client and Server must be configured and successfully deployed (i.e., with `configure`) before adding another Server. Servers can attach to any other Server *or* the Client itself. +The `add server` command is meant to extend the Wiretap network to reach new areas of a target network. At least one Client and Server must be configured and successfully deployed (i.e., with `configure`) before adding another Server. Servers can attach to any other Server *or* the Client itself. > [!WARNING] > Due to the way new Clients are added to existing networks, all Servers must be deployed *before* adding additional Clients. Added Clients won't be able to access Servers deployed after they were added. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. @@ -247,6 +272,14 @@ In this example, we will to the server with API address `::2`, which is listenin ```bash ./wiretap add server --server-address ::2 --endpoint 10.0.0.2:51820 --routes 10.0.1.0/24 ``` + + +--- + +
+ +Click to view output + ``` Configurations successfully generated. Import the updated config(s) into WireGuard locally and pass the arguments below to Wiretap on the new remote server. @@ -278,6 +311,10 @@ POSIX Shell: WIRETAP_RELAY_INTERFACE_PRIVATEKEY=sLERnxT2+VdwwcJOTUHK5fa5sIN7oJ1 Config File: ./wiretap serve -f wiretap_server_1.conf ``` +
+ +--- + The Client's E2EE configuration (`wiretap.conf`) will be modified to allow communication with the new Server, so you need to reimport it. For example, `sudo wg-quick down ./wiretap.conf && sudo wg-quick up ./wiretap.conf`. If you are attaching a new Server directly to the Client, the Relay interface will also need to be refreshed in the same way. Now you can use any of the `serve` command options to start Wiretap on the new Server. It will then join the Wiretap network by connecting to the existing Server. @@ -328,7 +365,7 @@ Now the Client can reach `10.0.0.0/24` and `10.0.1.0/24`. From here you can atta ![Wiretap Add Client Arguments](media/Wiretap_Add_Client.svg) -The `add client` subcommand can be used to share access to the Wiretap network with others. +The `add client` command can be used to share access to the Wiretap network with others. > [!WARNING] > All servers must be deployed *before* adding additional clients. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. @@ -338,6 +375,13 @@ Adding a new Client is very similar to the other commands. It will generate a `w ```bash ./wiretap add client --endpoint 1.3.3.8:1337 --port 1337 ``` + +--- + +
+ +Click to view output + ``` Configurations successfully generated. Have a friend import these files into WireGuard @@ -376,6 +420,10 @@ Endpoint = 172.17.0.3:51821 ──────────────────────────────── ``` +
+ +--- + Send these files and have the recipient import them into WireGuard to have access to everything in the Wiretap network! By default the routes (AllowedIPs) are copied over to the new client configs, but can be modified by the recipient as needed. ## Expose (Port Forwarding) @@ -383,7 +431,7 @@ Send these files and have the recipient import them into WireGuard to have acces > **Warning** > Port forwarding exposes ports and services on your local machine to the remote network, use with caution -You can expose a port on the Client to IPs in Wiretap's `routes` list by using the `expose` subcommand. For example, to allow remote systems to access port 80/tcp on your local Client machine, you could run: +You can expose a port on the Client to IPs in Wiretap's `routes` list by using the `expose` command. For example, to allow remote systems to access port 80/tcp on your local Client machine, you could run: ``` ./wiretap expose --local 80 --remote 8080 @@ -391,7 +439,7 @@ You can expose a port on the Client to IPs in Wiretap's `routes` list by using t Now all Wiretap Servers will be bound to listen on port 8080/tcp and proxy connections to your service on port 80/tcp. By default this uses IPv6, so make sure any exposed services listening on the Client support IPv6 as well. -To configure Wiretap to only use IPv4, use the `configure` subcommand's `--disable-ipv6` option. +To configure Wiretap to only use IPv4, use the `configure` command's `--disable-ipv6` option. > [!WARNING] > If a Wiretap server process exits or dies for any reason it will not remember ports it was previously exposing. You will need to re-expose any ports you configured with this command. @@ -435,33 +483,6 @@ To build secure and scalable tunnels across multiple hops, each node in the Wire ![Wiretap E2EE Architecture](media/Wiretap_E2EE.svg) -# Help - -```bash -./wiretap --help --show-hidden -``` -``` -Usage: - wiretap [flags] - wiretap [command] - -Available Commands: - add Add peer to wiretap - configure Build wireguard config - expose Expose local services to servers - help Help about any command - ping Ping wiretap server API - serve Listen and proxy traffic into target network - status Show peer layout - -Flags: - -h, --help help for wiretap - -H, --show-hidden show hidden flag options - -v, --version version for wiretap - -Use "wiretap [command] --help" for more information about a command. -``` - # Features * Network From f879b86d43a2c067fe22fc53e2a39cece4284e56 Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 15:40:24 -0600 Subject: [PATCH 08/22] better e2ee diagram --- media/Wiretap_E2EE.drawio | 191 +++++++++++++++++++++++++++----------- media/Wiretap_E2EE.svg | 2 +- 2 files changed, 139 insertions(+), 54 deletions(-) diff --git a/media/Wiretap_E2EE.drawio b/media/Wiretap_E2EE.drawio index 6ce1ea2..f61866c 100644 --- a/media/Wiretap_E2EE.drawio +++ b/media/Wiretap_E2EE.drawio @@ -1,34 +1,52 @@ - + - + - + - - + + - + + + + + + + + + + + + + + + + - - + + - - + + + + + - + - - + + @@ -47,8 +65,8 @@ - - + + @@ -69,26 +87,32 @@ - + - + + + + - - + + - + - + - + - - + + + + + @@ -123,21 +147,18 @@ - + - + - - - @@ -151,55 +172,119 @@ - + + - + - + - + - + - + - - + + - + - - + + - - - - + - - - - + - - + + - - + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/media/Wiretap_E2EE.svg b/media/Wiretap_E2EE.svg index dd74697..08a1c28 100644 --- a/media/Wiretap_E2EE.svg +++ b/media/Wiretap_E2EE.svg @@ -1,4 +1,4 @@ -

Client

Server 1


WireGuard End-to-End Encrypted Interface

WireGuard Relay
Interface
Unencrypted
End-To-End Encrypted
Relay Encrypted

Server 2
 \ No newline at end of file +

Client

Server 1


WireGuard End-to-End Encrypted Interface

WireGuard Relay
Interface
Unencrypted
End-To-End Encrypted
Relay Encrypted

Server 2
Wireguard Encryption/
Decryption Keys
 \ No newline at end of file From e201aaa41c819e821a7e4e801eb3ca805fc6373d Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 16:51:48 -0600 Subject: [PATCH 09/22] ToC; Combine How it Works --- README.md | 71 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 41 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index f601326..ea19a3c 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,17 @@ In this diagram, the Client has generated and installed WireGuard configuration ![Wiretap Diagram](media/Wiretap_Animated.svg) +# Table of Contents +[Terminology and Requirements](#Terminology-and-Requirements) +[Quick Start](#Quick-Start) +[Installation](#Installation) +[How it Works](#How-it-Works) +[Usage](#Usage) +[Features](#Features) +[Demo](#Demo) +[Experimental](#Experimental) + + # Terminology and Requirements A Wiretap Server is any machine where a Wiretap binary is running the `serve` command. Servers generate and receive network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." @@ -66,18 +77,31 @@ Feel free to skip this section, but understanding how Wiretap works at a high le > [!NOTE] > This section is intended to provide an intuitive, working understanding of how Wiretap works, and may not be entirely technically accurate about implementation details. +## Summary + +Traditional VPN server software can't be installed by unprivileged users because VPNs rely on dangerous operations like changing network routes and working with raw packets. + +Wiretap bypasses this requirement by rerouting traffic to a user-space TCP/IP network stack, where a listener accepts connections on behalf of the true destination. Then it creates a new connection to the true destination (via the native network stack) and copies data between the connections, effectively connecting the Client to the destination. This is similar to how https://github.com/sshuttle/sshuttle and https://github.com/nicocha30/ligolo-ng work, but relies on WireGuard as the tunneling mechanism rather than SSH or TLS. + +To build secure and scalable tunnels across multiple hops, each node in the Wiretap network has two interfaces: Relay and E2EE (End-to-End Encrypted). The Relay interfaces simply *relay* packets between nodes, but cannot see the plaintext. When a Relay node sees a packet that does not match routing rules, it forwards it to its own E2EE interface where the contents can be decrypted by only that interface. This means there are two layers of WireGuard encapsulation (encryption) between any two nodes. + +
+ +![Wiretap E2EE Architecture](media/Wiretap_E2EE.svg) +
-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. +## Details +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 are very similar to how Wireguard is traditionally used. Relay interfaces receive internal Wireguard IPs: `172.16.X.X` for IPv4, and `fd:16::X` for IPv6. -Inside the relay tunnels, Wiretap establishes a second virtual End-to-End Encrypted (`EE2E`) network (`wiretap.conf`). This network is invisible to the real-world network. Each Server and Client gets its own unique internal IP addresses inside this network: `172.X.X.X` for IPv4, and `fd:XX::X` for IPv6. As the EE2E name suggests, each Client-Server pair within this virtual network become Wireguard peers, able to generate encrypted messages that only the other can decrypt. +Inside the Relay 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. -Wiretap Clients track which real-world IP ranges ("routes") have been assigned to each Server inside the relay network. When the Client machine generates a packet destined for a known Wiretap route, Wireguard encrypts it using the EE2E configuration associated with the Server assigned to that route. The encrypted packet (now a UDP datagram) gets marked with the E2EE IP address of the assigned server as its destination. +Wiretap Clients track which real-world IP ranges ("routes") have been assigned to each Server inside the Relay network. When the 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 can decrypt. The Server receives the datagram, decrypts the relay encryption, identifies which of its peer servers in the relay network the EE2E datagram should be sent to next, and sends it off via the associated relay tunnel. +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 sends the packet to the real-world IP address indicated in the packet header, and forwards any response packets back to the Client using the same process. -Within the E2EE network (i.e., accessible only to Clients), Wiretap Servers expose an API to enable real-time configuration changes and to monitor the health of the Wiretap network. Each Server is assigned an additional unique IP (usually an IPv6 address) inside the E2EE network to enable the secure usage of this API. This IP is referred to as the "API address." +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. Each Server is dynamically assigned an additional unique 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." # Usage @@ -109,9 +133,9 @@ Use "wiretap [command] --help" for more information about a command. The following commands are documented in this section: * [configure](#Configure) * [serve](#Serve) -* [add server](#Add-Server-(Optional)) -* [add client](#Add-Client-(Optional)) -* [expose](#Expose-(Port-Forwarding)) +* [add server](#Add-Server-Optional) +* [add client](#Add-Client-Optional) +* [expose](#Expose-Port-Forwarding) Get help for any command by adding the `-h` flag to it. @@ -470,19 +494,6 @@ Use `./wiretap expose remove` with the same arguments used in `expose` to delete ./wiretap expose remove --dynamic --remote 8080 ``` -# How It Works - -A traditional VPN can't be installed by unprivileged users because VPNs rely on dangerous operations like changing network routes and working with raw packets. - -Wiretap bypasses this requirement by rerouting traffic to a user-space TCP/IP network stack, where a listener accepts connections on behalf of the true destination. Then it creates a new connection to the true destination and copies data between the endpoint and the peer. This is similar to how https://github.com/sshuttle/sshuttle and https://github.com/nicocha30/ligolo-ng work, but relies on WireGuard as the tunneling mechanism rather than SSH or TLS. - -To build secure and scalable tunnels across multiple hops, each node in the Wiretap network has two interfaces: Relay and E2EE (end-to-end encrypted). The Relay nodes simply *relay* packets between nodes, but cannot see the plaintext. When a Relay node sees a packet that does not match routing rules, it forwards it to its own E2EE interface where contents can be decrypted by only that interface. There are two layers of WireGuard encapsulation between any two nodes. - -
- -![Wiretap E2EE Architecture](media/Wiretap_E2EE.svg) -
- # Features * Network @@ -526,23 +537,23 @@ If you have *no* outbound or inbound UDP access, you can still use Wiretap, but Another great tool that has similar cross-platform capabilities to Wiretap is [Chisel](https://github.com/jpillora/chisel). We can use chisel to forward a UDP port to the remote system over TCP. To use: -Run `chisel server` on the wiretap client system, specifying a TCP port you can reach from the server system: +Run `chisel server` on the Wiretap Client, specifying a TCP listening port that the Wiretap Server can reach: ```bash ./chisel server --port 8080 ``` > [!Note] -> In this example we run the `chisel server ...` command on the Wiretap *client*, and `chisel client ...` command on a Wiretap *server*. This is because the chisel "client" always tries to reach out and connect to the chisel "server," whereas Wiretap clients and servers are defined by their functionality since either can initiate the connection. +> In this example we run the `chisel server ...` command on the Wiretap *Client*, and `chisel client ...` command on a Wiretap *Server*. This is because the chisel "client" always initiates the connection to the chisel "server;" Wiretap Clients and Servers are defined by their functionality, not by which one initiates the connection. -In this example, we're connecting chisel to the listener on 8080 (on the wiretap client) and forwarding 61820/udp from the Wiretap server to 51820 (any interface) on the Wiretap client: +In this example, we're connecting chisel to the listener on 8080 (on the Wiretap Client) and forwarding 61820/udp from the Wiretap Server to 51820 (any interface) on the Wiretap Client: ```bash ./chisel client :8080 61820:0.0.0.0:51820/udp ``` - `8080` is the chisel listening port specified in the `chisel server` command above -- `61820` is the localhost port on the Wiretap server that will be forwarded back to the Wiretap client. -- `51820` is the port where the Wiretap client is listening (by default is the same port you specified in the `--endpoint` argument in the initial `wiretap configure` command) +- `61820` is the localhost port on the Wiretap Server that will be forwarded back to the Wiretap Client. +- `51820` is the port where the Wiretap Client is listening -Finally, run Wiretap on the remote server system with the forwarded localhost port in the `--endpoint`: +Finally, run Wiretap on the remote server system, using the forwarded localhost port in the `--endpoint` argument: ```bash WIRETAP_RELAY_INTERFACE_PRIVATEKEY= WIRETAP_RELAY_PEER_PUBLICKEY= WIRETAP_E2EE_INTERFACE_PRIVATEKEY= WIRETAP_E2EE_PEER_PUBLICKEY= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve --endpoint localhost:61820 ``` @@ -552,9 +563,9 @@ WIRETAP_RELAY_INTERFACE_PRIVATEKEY= WIRETAP_RELAY_PEER_PUBLICKEY= WIRE > [!NOTE] > Clients added to arbitrary servers do not currently have the same capabilities as clients added to first-hop servers (the default) -Clients can be attached to any server in the network by using the `--server-address ` argument when running `wiretap add client`. This allows a client on a different network than the first client to still gain access to all of the Wiretap network's routes. But this has some limitations. +Clients can be attached to any Server in the network by using the `--server-address ` argument when running `wiretap add client`. This allows a Client on a different network than the first Client to still gain access to all of the Wiretap network's routes. However, the new Client will not be able to access any Servers that are part of a different chain connected to the first Client. -In this example, a new client (C2) is added to the second server in the right branch of a Wiretap network (S4). This client will only be able to access routes via the right branch of the network (S3 and S4) and not the left branch (S1 or S2) because the branches are only joined through an existing client (C1), which does not route traffic from other clients: +As an example, consider a new Client (C2) that is added to the second server (S4) in the right branch of a Wiretap network. This new Client will only be able to access routes via the right branch of the network (S3 and S4) and not the left branch (S1 or S2) because the branches are only joined through an existing Client (C1). Clients does not route traffic from other Clients. ``` ┌──────┐ @@ -573,4 +584,4 @@ In this example, a new client (C2) is added to the second server in the right br └──────┘ ``` -You may also need to manually edit the resulting `wiretap.conf` for the new client to remove any `AllowedIPs` entries that already exist in the new client's host routing table. If the server that the client is attaching to has a route for 10.2.0.0/16, but the Client already has that route (because that's where it lives), then remove the `10.2.0.0/16` entry from the `wiretap.conf` file before importing into WireGuard. Leave the API address and any other routes you wish to access. +You may also need to manually edit the resulting `wiretap.conf` for the new Client to remove any `AllowedIPs` entries that already exist in the new Client's host routing table. For example, if the Server that the Client is attaching to was assigned a route for 10.2.0.0/16, but the Client already has that route (because that's the subnet where it lives), then remove the `10.2.0.0/16` entry from the `wiretap.conf` file before importing into WireGuard. Leave the API address and any other routes the new Client wishes to access. From 3df14938d3593c4de8b377f76016771f3bce8155 Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 16:55:48 -0600 Subject: [PATCH 10/22] ToC fix --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ea19a3c..e0e278b 100644 --- a/README.md +++ b/README.md @@ -13,14 +13,14 @@ In this diagram, the Client has generated and installed WireGuard configuration # Table of Contents -[Terminology and Requirements](#Terminology-and-Requirements) -[Quick Start](#Quick-Start) -[Installation](#Installation) -[How it Works](#How-it-Works) -[Usage](#Usage) -[Features](#Features) -[Demo](#Demo) -[Experimental](#Experimental) +- [Terminology and Requirements](#Terminology-and-Requirements) +- [Quick Start](#Quick-Start) +- [Installation](#Installation) +- [How it Works](#How-it-Works) +- [Usage](#Usage) +- [Features](#Features) +- [Demo](#Demo) +- [Experimental](#Experimental) # Terminology and Requirements From 5bf32d86fc39ce2fb7024119bf098dc18558e65f Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 16:59:20 -0600 Subject: [PATCH 11/22] bigger SVG render size --- media/Wiretap_E2EE.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/media/Wiretap_E2EE.svg b/media/Wiretap_E2EE.svg index 08a1c28..4eb6b65 100644 --- a/media/Wiretap_E2EE.svg +++ b/media/Wiretap_E2EE.svg @@ -1,4 +1,4 @@ -

Client

Server 1


WireGuard End-to-End Encrypted Interface

WireGuard Relay
Interface
Unencrypted
End-To-End Encrypted
Relay Encrypted

Server 2
Wireguard Encryption/
Decryption Keys
 \ No newline at end of file +

Client

Server 1


WireGuard End-to-End Encrypted Interface

WireGuard Relay
Interface
Unencrypted
End-To-End Encrypted
Relay Encrypted

Server 2
Wireguard Encryption/
Decryption Keys
 \ No newline at end of file From d6f04211f30487f9cbf69bd296acd375787f2b17 Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 17:04:51 -0600 Subject: [PATCH 12/22] raw image link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e0e278b..24a1219 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ To build secure and scalable tunnels across multiple hops, each node in the Wire
-![Wiretap E2EE Architecture](media/Wiretap_E2EE.svg) +![Wiretap E2EE Architecture](media/Wiretap_E2EE.svg?raw=true)
## Details From b4a6049e8d5a21200fe920e2d49e31f343bba7bf Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 17:09:03 -0600 Subject: [PATCH 13/22] image instruction --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 24a1219..cbe6ce7 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,8 @@ To build secure and scalable tunnels across multiple hops, each node in the Wire
![Wiretap E2EE Architecture](media/Wiretap_E2EE.svg?raw=true) + +(Click image to view enlarged version)
## Details From 6f1e098edda408cf3ac8efeecc0c5c4b4cecce6b Mon Sep 17 00:00:00 2001 From: amerril Date: Tue, 1 Oct 2024 17:15:09 -0600 Subject: [PATCH 14/22] Additional headers --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cbe6ce7..825d1e5 100644 --- a/README.md +++ b/README.md @@ -93,16 +93,21 @@ To build secure and scalable tunnels across multiple hops, each node in the Wire ## Details + +### Relay Network 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 are very similar to how Wireguard is traditionally used. Relay interfaces receive internal Wireguard IPs: `172.16.X.X` for IPv4, and `fd:16::X` for IPv6. +### E2EE Network Inside the Relay 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. +### Routing Wiretap Clients track which real-world IP ranges ("routes") have been assigned to each Server inside the Relay network. When the 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 sends the packet to the real-world IP address indicated in the packet header, and forwards any response packets back to the Client using the same process. +### API 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. Each Server is dynamically assigned an additional unique 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." # Usage @@ -161,7 +166,7 @@ On the Client machine, run Wiretap's `configure` command to generate starting co * `--routes` is the equivalent of WireGuard's `AllowedIPs` setting. This tells the Client to route traffic that matches these IP ranges through Wiretap. > [!IMPORTANT] -> By default the listening port will be configured to be the same as the port specified in the `--endpoint` IP:port. This can be overwritten using the `--port` argument. +> By default the listening port will be configured to be the same as the port specified in the `--endpoint IP:port`. This can be overwritten using the `--port` argument. Following the example in the diagram: ```bash From 44926d6345d0229356f39130c7b07f4497e48be1 Mon Sep 17 00:00:00 2001 From: amerril Date: Thu, 3 Oct 2024 16:49:44 -0600 Subject: [PATCH 15/22] Moved HiW to Wiki --- README.md | 28 +++------------------------- 1 file changed, 3 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 825d1e5..b84b9c5 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ In this diagram, the Client has generated and installed WireGuard configuration A Wiretap Server is any machine where a Wiretap binary is running the `serve` command. Servers generate and receive network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." -A Wiretap Client is any machine running the Wireguard configurations necessary to send network traffic through a Wiretap Server. It functions much like a client in a VPN connection. +A Wiretap Client is any machine running the Wireguard configurations necessary to send network traffic through a Wiretap Server. It functions much like a client in a VPN connection. Clients are also able to reconfigure parts of the Wiretap network dynamically using the Wiretap binary. > [!IMPORTANT] > Unlike the typical use of "client" and "server" terms in networking, Wiretap's Client and Server terms have nothing to do with which machine listens for or initiates the initial connection. @@ -72,12 +72,8 @@ If you want to compile it yourself or can't find the OS/ARCH you're looking for, # How it Works -Feel free to skip this section, but understanding how Wiretap works at a high level is very helpful for troubleshooting when you run into issues or errors. Additionally, some of the documentation below assumes you've read this. - -> [!NOTE] -> This section is intended to provide an intuitive, working understanding of how Wiretap works, and may not be entirely technically accurate about implementation details. - -## Summary +> [!TIP] +> For a more detailed explanation of Wiretap's networking model, see the [How it Works page in the Wiki](https://github.com/sandialabs/wiretap/wiki/How-it-Works). That information can be very helpful when trying to troubleshoot connection issues. Traditional VPN server software can't be installed by unprivileged users because VPNs rely on dangerous operations like changing network routes and working with raw packets. @@ -92,24 +88,6 @@ To build secure and scalable tunnels across multiple hops, each node in the Wire (Click image to view enlarged version) -## Details - -### Relay Network -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 are very similar to how Wireguard is traditionally used. Relay interfaces receive internal Wireguard IPs: `172.16.X.X` for IPv4, and `fd:16::X` for IPv6. - -### E2EE Network -Inside the Relay 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. - -### Routing -Wiretap Clients track which real-world IP ranges ("routes") have been assigned to each Server inside the Relay network. When the 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 sends the packet to the real-world IP address indicated in the packet header, and forwards any response packets back to the Client using the same process. - -### API -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. Each Server is dynamically assigned an additional unique 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." - # Usage ```bash From bfa83731536d9490fe80a8b63859252e1090cc77 Mon Sep 17 00:00:00 2001 From: amerril Date: Mon, 21 Oct 2024 17:54:58 -0600 Subject: [PATCH 16/22] various diagram updates; add static version of overview --- media/Wiretap_Add_Client.drawio | 196 +++++++++++++++- media/Wiretap_Add_Client.svg | 21 +- media/Wiretap_Add_Server.drawio | 160 ++++++++++++- media/Wiretap_Add_Server.svg | 20 +- media/Wiretap_Animated.svg | 6 +- media/Wiretap_Configure.drawio | 142 ++++++++++- media/Wiretap_Configure.svg | 20 +- media/Wiretap_Static.svg | 405 ++++++++++++++++++++++++++++++++ 8 files changed, 912 insertions(+), 58 deletions(-) create mode 100644 media/Wiretap_Static.svg diff --git a/media/Wiretap_Add_Client.drawio b/media/Wiretap_Add_Client.drawio index 1be56d8..662f8b3 100644 --- a/media/Wiretap_Add_Client.drawio +++ b/media/Wiretap_Add_Client.drawio @@ -1 +1,195 @@ -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 \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/media/Wiretap_Add_Client.svg b/media/Wiretap_Add_Client.svg index daee3fe..58c0abb 100644 --- a/media/Wiretap_Add_Client.svg +++ b/media/Wiretap_Add_Client.svg @@ -1,18 +1,3 @@ - -ServerServer10.0.0.210.0.0.2  client$ ./wiretap add client --port 1337 --endpoint 1.3.3.8:1337client$ ./wiretap add client...--port 1337 configures the new Client's WireGuard listening port--port 1337 config...--endpoint 1.3.3.8:1337 tells the first-hop Server how to connect to the new Client--endpoint 1.3.3.8:1337 tells the... -Internal NetworkInterna... -New ServerNew Server10.0.0.310.0.0.3 -WireGuard TunnelWireGuard Tunnel -InternetInternet -New ClientNew Client1.3.3.81.3.3.8 -ClientClient1.3.3.71.3.3.7Text is not SVG - cannot display \ No newline at end of file + + +

Server
10.0.0.2
  client$ ./wiretap add client
--endpoint 7.3.3.2:1337
--port 1337 
configures the new Client's WireGuard listening port; 
if omitted, will copy the 
--endpoint port value 
--endpoint 7.3.3.2:1337 
tells the existing first-hop Server how to connect to the new Client

Internal Network

New Server
10.0.0.3

WireGuard Tunnel

Internet

New Client
7.3.3.2

Client
7.3.3.1
 \ No newline at end of file diff --git a/media/Wiretap_Add_Server.drawio b/media/Wiretap_Add_Server.drawio index 62bfd46..c4b3ec2 100644 --- a/media/Wiretap_Add_Server.drawio +++ b/media/Wiretap_Add_Server.drawio @@ -1 +1,159 @@ -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 \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/media/Wiretap_Add_Server.svg b/media/Wiretap_Add_Server.svg index 8dd0806..87ec880 100644 --- a/media/Wiretap_Add_Server.svg +++ b/media/Wiretap_Add_Server.svg @@ -1,17 +1,3 @@ - -ServerServer10.0.0.210.0.0.2  client$ ./wiretap add server        --server-address ::2 --endpoint 10.0.0.2:51820 --routes 10.0.1.0/24client$ ./wiretap add server...--server-address ::2configures routing for existing Servers --server-address ::2...--routes 10.0.1.0/24configures the Client machine to route traffic destined for this subnet through the new Server--routes 10.0.1.0/24... -Internal NetworkInterna... -New ServerNew Server10.0.0.310.0.0.3 -WireGuard TunnelWireGuard Tunnel -InternetInternet -ClientClient1.3.3.71.3.3.7--endpoint 10.0.0.2:51820tells the new Server how to connect to an existing Server--endpoint 10.0.0.2:51820...Text is not SVG - cannot display \ No newline at end of file + + +

Server
10.0.0.2
  client$ ./wiretap add server
        --server-address ::2
--endpoint 10.0.0.2:51820
--routes 10.0.1.0/24
--server-address ::2
API address of target existing Server; used to configure the new connection
--routes 10.0.1.0/24
configures the Client machine to route traffic destined for this subnet through the new Server

Internal Network

New Server
10.0.0.3

WireGuard Tunnel

Internet

Client
7.3.3.1
--endpoint 10.0.0.2:51820
tells the new Server how to connect to an existing Server
 \ No newline at end of file diff --git a/media/Wiretap_Animated.svg b/media/Wiretap_Animated.svg index 7656e22..16a61ed 100644 --- a/media/Wiretap_Animated.svg +++ b/media/Wiretap_Animated.svg @@ -311,11 +311,11 @@
-
1.3.3.7
+
7.3.3.1
 - 1.3.3.7 + 7.3.3.1 @@ -477,4 +477,4 @@ Text is not SVG - cannot display - \ No newline at end of file + diff --git a/media/Wiretap_Configure.drawio b/media/Wiretap_Configure.drawio index fd9dd9e..49b8a68 100644 --- a/media/Wiretap_Configure.drawio +++ b/media/Wiretap_Configure.drawio @@ -1 +1,141 @@ -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 \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/media/Wiretap_Configure.svg b/media/Wiretap_Configure.svg index b502fb8..eedede1 100644 --- a/media/Wiretap_Configure.svg +++ b/media/Wiretap_Configure.svg @@ -1,17 +1,3 @@ - -ServerServer10.0.0.210.0.0.2  client$ ./wiretap configure --port 1337 --endpoint 1.3.3.7:1337 --routes 10.0.0.0/24client$ ./wiretap configure...--port 1337 configures the Client's WireGuard listening port--port 1337 config...--endpoint 1.3.3.7:1337 tells the Server how to connect to the Client--endpoint 1.3.3.7:1337 tells th...--routes 10.0.0.0/24configures the Client's machine to route traffic destined for this subnet through the WireGuard Tunnel--routes 10.0.0.0/24... -Internal NetworkInterna... -TargetTarget10.0.0.310.0.0.3 -ClientClient1.3.3.71.3.3.7 -WireGuard TunnelWireGuard Tunnel -InternetInternetText is not SVG - cannot display \ No newline at end of file + + +

Server
10.0.0.2
  client$ ./wiretap configure
--endpoint 7.3.3.1:1337
--routes 10.0.0.0/24
--port 1337 
configures the Client's WireGuard listening port; if omitted, will copy the --endpoint port value
--endpoint 7.3.3.1:1337 tells the Server how to connect to the Client
--routes 10.0.0.0/24
configures the Client's machine to route traffic destined for this subnet through the WireGuard Tunnel

Internal Network

Target
10.0.0.3

Client
7.3.3.1

WireGuard Tunnel

Internet
 \ No newline at end of file diff --git a/media/Wiretap_Static.svg b/media/Wiretap_Static.svg new file mode 100644 index 0000000..e2a1fc0 --- /dev/null +++ b/media/Wiretap_Static.svg @@ -0,0 +1,405 @@ + + + + + + + + + + +
+
+
+ client$ + ping 10.0.0.3
+ +
+ PING 10.0.0.3 (10.0.0.3): 56 data bytes
+ +
+ +
+
+
+
+ + client$ ping 10.0.0.3... + + + + + + +
+
+
+ + 1. Client deploys Wiretap to Server. Wiretap handshakes with Client via UDP, opening up the firewall + +
+
+
+ + 1. Client deploys Wiretap to Ser... + + + + + + + + + + +
+
+
+ + 2. Client routes traffic destined for 10.0.0.0/24 through WireGuard interface, then communicates with resources local to the Server + +
+
+
+ + 2. Client routes traffic des... + + + + + + + + + +
+
+
+
+ ICMP Echo Request +
+
+
+
+ + ICMP Echo Request + + + + + + + + + + +
+
+
+
+ ICMP Echo Reply +
+
+
+
+ + ICMP Echo Reply + + + + + + + + + + +
+
+
+ WireGuard Tunnel +
+
+
+ + WireGuard Tunnel + + + + + + +
+
+
+ 64 bytes from 10.0.0.3: icmp_seq=0 ttl=64 time=76.045 ms +
+
+ +
+
+
+
+ + 64 bytes from 10.0.0.3: icmp_seq=0 ttl=64 time=76.045 ms + + + + + + +
+
+
+
+
+ +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + +
+
+
+
Internal Network
+
+
+
+ + Interna... + + + + + + +
+
+
+
+
+ +
+
+
+
+ + + + + + + +
+
+
Client
+
+
+ + Client + + + + + +
+
+
7.3.3.1
+
+
+ + 7.3.3.1 + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+
+ +
+
+
+
+ + + + + + + +
+
+
+ Internet +
+
+
+ + Internet + + + + + + + + + + + + + + +
+
+
+
+
+ +
+
+
+
+ + + + + + + +
+
+
Target
+
+
+ + Target + + + + + +
+
+
10.0.0.3
+
+
+ + 10.0.0.3 + + + + + + +
+
+
+
+
+ +
+
+
+
+ + + + + + + +
+
+
Server
+
+
+ + Server + + + + + +
+
+
10.0.0.2
+
+
+ + 10.0.0.2 + + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + From b4c414734990f27c6934e615a23d4af52a8c8b77 Mon Sep 17 00:00:00 2001 From: amerril Date: Mon, 21 Oct 2024 17:56:18 -0600 Subject: [PATCH 17/22] document more flags; consistency and readability improvements --- README.md | 65 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 39 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index b84b9c5..44e3a23 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,13 @@ Wiretap is a transparent, VPN-like proxy server that tunnels traffic via WireGuard and requires no special privileges to run. -In this diagram, the Client has generated and installed WireGuard configuration files that will route traffic destined for `10.0.0.0/24` through a WireGuard interface. Wiretap is then deployed to the Server with a configuration that connects to the Client as a WireGuard peer. The client can then interact with resources local to the Server as if on the same network, and optionally chain additional servers to reach new networks. Access to the Wiretap network can also be shared with other Clients. +In this diagram, the Client has generated and installed WireGuard configuration files that will route traffic destined for `10.0.0.0/24` through a WireGuard interface. Wiretap is then deployed to the Server with a configuration that connects to the Client as a WireGuard peer. The Client can then interact with local network resources as if on the same network as the Server, and optionally chain additional Servers to reach new networks. Access to the Wiretap network can also be shared with other Clients.
![Wiretap Diagram](media/Wiretap_Animated.svg) + +[(Static Version)](media/Wiretap_Static.svg?raw=true)
# Table of Contents @@ -25,17 +27,17 @@ In this diagram, the Client has generated and installed WireGuard configuration # Terminology and Requirements -A Wiretap Server is any machine where a Wiretap binary is running the `serve` command. Servers generate and receive network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." +A Wiretap Server is any machine where a Wiretap binary is running the `serve` command. Servers receive and relay network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." -A Wiretap Client is any machine running the Wireguard configurations necessary to send network traffic through a Wiretap Server. It functions much like a client in a VPN connection. Clients are also able to reconfigure parts of the Wiretap network dynamically using the Wiretap binary. +A Wiretap Client is any machine running the [Wireguard](https://www.wireguard.com/) configurations necessary to send and receive network traffic through a Wiretap Server. It functions much like a client in a VPN connection. Clients are also able to reconfigure parts of the Wiretap network dynamically using the Wiretap binary. > [!IMPORTANT] > Unlike the typical use of "client" and "server" terms in networking, Wiretap's Client and Server terms have nothing to do with which machine listens for or initiates the initial connection. ## Client System Requirements -* WireGuard - https://www.wireguard.com/install/ -* Privileged access necessary to configure WireGuard +* WireGuard installed - https://www.wireguard.com/install/ +* Privileged access necessary to configure WireGuard interfaces (usually root/admin access) ## Server System Requirements @@ -45,20 +47,20 @@ A Wiretap Client is any machine running the Wireguard configurations necessary t ## Environment Requirements -* Bidirectional UDP communication between Server and Client on one port. Any firewalls between them must allow at least one machine to initiate the UDP connection to the other. +* Bidirectional UDP communication between Server and Client on one port. Any firewalls between them must allow at least one machine to initiate a UDP connection to the other. * The machine receiving the initial connection (the Client by default) must be able to listen for UDP connections on a port that the initiating machine can connect to. > [!NOTE] > By default the Server initiates the handshake to the Client because the Server is more likely to have outbound UDP allowed through a firewall than inbound UDP, but the reverse is easily configurable. -While not ideal, Wiretap can still work with TCP instead of UDP. See the experimental [TCP Tunneling](#tcp-tunneling) section for more info. +While not ideal, Wiretap can work with TCP instead of UDP. See the experimental [TCP Tunneling](#tcp-tunneling) section for more info. # Quick Start 1. Download binaries from the [releases](https://github.com/sandialabs/wiretap/releases) page, one for your Client machine and one for your Server machine (if different os/arch). Copy the Wiretap binary onto the server -2. On the Client, run `./wiretap configure --endpoint : --routes ` with the appropriate arguments +2. On the Client, run `./wiretap configure --endpoint : --routes ` with the [appropriate arguments](#Configure) 3. Copy the server command output that best suits the Server OS and run it on the Server machine -4. On the Client, run `sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf` to import the configs into Wireguard +4. On the Client, run `sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf` create the associated Wireguard interfaces 5. Confirm the handshake completed for both configs by running `sudo wg show` on the Client 6. (Optional) Add more servers and clients as needed with the `wiretap add` command @@ -148,7 +150,7 @@ On the Client machine, run Wiretap's `configure` command to generate starting co Following the example in the diagram: ```bash -./wiretap configure --endpoint 1.3.3.7:1337 --routes 10.0.0.0/24 +./wiretap configure --endpoint 7.1.1.3:1337 --routes 10.0.0.0/24 ``` --- @@ -192,8 +194,8 @@ Endpoint = 172.17.0.2:51821 server config: wiretap_server.conf server command: -POSIX Shell: WIRETAP_RELAY_INTERFACE_PRIVATEKEY=WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y= WIRETAP_RELAY_INTERFACE_PORT=51820 WIRETAP_RELAY_PEER_PUBLICKEY=Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc= WIRETAP_RELAY_PEER_ENDPOINT=1.3.3.7:1337 WIRETAP_E2EE_INTERFACE_PRIVATEKEY=GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg= WIRETAP_E2EE_PEER_PUBLICKEY=cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve - PowerShell: $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_INTERFACE_PORT="51820"; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="1.3.3.7:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve +POSIX Shell: WIRETAP_RELAY_INTERFACE_PRIVATEKEY=WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y= WIRETAP_RELAY_INTERFACE_PORT=51820 WIRETAP_RELAY_PEER_PUBLICKEY=Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc= WIRETAP_RELAY_PEER_ENDPOINT=7.1.1.3:1337 WIRETAP_E2EE_INTERFACE_PRIVATEKEY=GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg= WIRETAP_E2EE_PEER_PUBLICKEY=cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve + PowerShell: $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_INTERFACE_PORT="51820"; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="7.1.1.3:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve Config File: ./wiretap serve -f wiretap_server.conf ``` @@ -205,32 +207,43 @@ Config File: ./wiretap serve -f wiretap_server.conf Install the resulting `wiretap_relay.conf` and `wiretap.conf` configs files into WireGuard on the Client: -* If using a GUI, select the menu option similar to *Import Tunnel(s) From File* * If you have `wg-quick` installed, run `sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf` +* If using a GUI, select the menu option similar to *Import Tunnel(s) From File* > [!TIP] -> You can modify the AllowedIPs in the `wiretap.conf` file any time after generating the config files, just reload the config file with `wg-quick down ./wiretap.conf && wg-quick up ./wiretap.conf` after making the change. No changes are needed on the server to update them. +> You can modify the AllowedIPs in the `wiretap.conf` file any time after generating the config files, just reload the config file with `wg-quick down ./wiretap.conf && wg-quick up ./wiretap.conf` (or re-import them into the GUI) after making the change. No changes are needed on the Server to update them. > [!WARNING] > In the default configuration, with the Client listening for an initial Server connection, the Server will still also listen on port 51820 so that other Servers can attach to it later. There is currently no way to change this when running the `configure` command, but when running `wiretap serve` you can manually change this in the `wiretap_server.conf` file, or using the `WIRETAP_RELAY_INTERFACE_PORT` environment variable. Don't forget to disable or remove the tunnels when you're done (e.g., `sudo wg-quick down ./wiretap.conf && sudo wg-quick down ./wiretap_relay.conf`) +### Outbound Connections +You can use the `--outbound` flag to configure the Client to Initiate the UDP connection to the Server. If you do, the `--endpoint` value will instead be used to tell the Client where to connect to the Server, and the `--port` value (explicit or implicit) will configure the Server's listening port. + +In this case the Client will listen on 51820 in case other Servers need to be added using the default Inbound mode, but this can be changed via the `ListenPort` variable in the `wiretap_relay.conf` file if needed. + +### Simple Mode +While not recommended, you can add the `--simple` flag to configure Wiretap as a more traditional one-Client-and-one-Server VPN. Most of Wiretap's dynamic configuration features (any Wiretap commands you would run after establishing the initial connection) will be unavailable in this mode. + +> [!WARNING] +> When starting the Server, you may need to also use the `--simple` flag. The Server currently does not support automatically detecting this configuration. + ## Serve -On the remote machine, upload the Wiretap binary and then run one of the commands from the output of `configure` to start Wiretap in server mode: +On the remote machine, upload the Wiretap binary and then run one of the commands from the output of `configure` to start Wiretap in Server mode: ```powershell $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_INTERFACE_PORT="51820"; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="1.3.3.7:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve ``` -There are two other ways to pass arguments to the server: -1. With the generated server config file: `-f wiretap_server.conf` -2. The legacy method of passing command line arguments (`--endpoint 1.3.3.7:1337 ...`). Be aware that this method exposes the arguments to other users on the system. A compromised private key can be used to connect to the client as a peer and/or decrypt traffic +There are two other ways to pass arguments to the Server: +1. With the generated Server config file: `-f wiretap_server.conf` +2. The legacy method of passing command line arguments (`--endpoint 7.1.1.3:1337 ...`). Be aware that this method exposes the arguments to other users on the system. A compromised private key can be used to connect to the Client as a peer and/or decrypt traffic > [!NOTE] > The wiretap_server.conf file uses a notation unique to Wiretap. It cannot be used to start a server with `wg-quick` or other generic Wireguard tools. -Confirm that the relay interfaces on the Client and Server have successfully completed a handshake. The Client should see successful handshakes in whatever WireGuard interface is running. If using the command-line tools, check with `sudo wg show`. By default the E2EE handshake will not occur until the Client sends data, so you may need to attempt to use the connection (e.g. `ping` an IP in the associated `--routes`) to trigger the handshake process. +Confirm that the Relay interfaces on the Client and Server have successfully completed a handshake. The Client should see successful handshakes in whatever WireGuard interface is running. If using the command-line tools, check with `sudo wg show`. By default the E2EE handshake will not occur until the Client sends data, so you may need to attempt to use the connection (e.g. `ping` an IP in the associated `--routes`) to trigger the handshake process. Now the Client should be able to interact with the `routes` specified in the `configure` command! @@ -324,7 +337,7 @@ Config File: ./wiretap serve -f wiretap_server_1.conf --- -The Client's E2EE configuration (`wiretap.conf`) will be modified to allow communication with the new Server, so you need to reimport it. For example, `sudo wg-quick down ./wiretap.conf && sudo wg-quick up ./wiretap.conf`. If you are attaching a new Server directly to the Client, the Relay interface will also need to be refreshed in the same way. +The Client's E2EE configuration (`wiretap.conf`) will be modified to allow communication with the new Server, so you need to re-import it. For example, `sudo wg-quick down ./wiretap.conf && sudo wg-quick up ./wiretap.conf`. If you are attaching a new Server directly to the Client, the Relay interface will also need to be refreshed in the same way. Now you can use any of the `serve` command options to start Wiretap on the new Server. It will then join the Wiretap network by connecting to the existing Server. @@ -382,7 +395,7 @@ The `add client` command can be used to share access to the Wiretap network with Adding a new Client is very similar to the other commands. It will generate a `wiretap.conf` and `wiretap_relay.conf` for sharing. Make sure that all of the first-hop Servers (any Server directly attached to the original Client) can reach or be reached by the new Client or else the new Client won't have access to that chain of Servers. Once you get the endpoint information from whoever will be running the new Client (the IP and port they will listen on), run: ```bash -./wiretap add client --endpoint 1.3.3.8:1337 --port 1337 +./wiretap add client --endpoint 7.1.1.4:1337 --port 1337 ``` --- @@ -446,7 +459,7 @@ You can expose a port on the Client to IPs in Wiretap's `routes` list by using t ./wiretap expose --local 80 --remote 8080 ``` -Now all Wiretap Servers will be bound to listen on port 8080/tcp and proxy connections to your service on port 80/tcp. By default this uses IPv6, so make sure any exposed services listening on the Client support IPv6 as well. +Now all existing Wiretap Servers will bind listeners on port 8080/tcp and proxy connections from that port to your local Client machine on port 80/tcp. By default this uses IPv6, so make sure any exposed services listening on the Client support IPv6 as well. To configure Wiretap to only use IPv4, use the `configure` command's `--disable-ipv6` option. @@ -459,13 +472,13 @@ To dynamically expose all ports on the Client using SOCKS5: ./wiretap expose --dynamic --remote 8080 ``` -All servers will spin up a SOCKS5 server on port 8080 and proxy traffic to your local machine and can be used like this: +All servers will spin up a SOCKS5 server on port 8080 and proxy traffic to your local machine. It and can be used like this: ``` -curl -x socks5://:8080 http://:1337 +curl -x socks5://:8080 http://:80 ``` -The destination IP will be rewritten by the server so you can put any address. +The destination IP will be rewritten by the Server so you can put any address. ### List @@ -550,7 +563,7 @@ WIRETAP_RELAY_INTERFACE_PRIVATEKEY= WIRETAP_RELAY_PEER_PUBLICKEY= WIRE Clients can be attached to any Server in the network by using the `--server-address ` argument when running `wiretap add client`. This allows a Client on a different network than the first Client to still gain access to all of the Wiretap network's routes. However, the new Client will not be able to access any Servers that are part of a different chain connected to the first Client. -As an example, consider a new Client (C2) that is added to the second server (S4) in the right branch of a Wiretap network. This new Client will only be able to access routes via the right branch of the network (S3 and S4) and not the left branch (S1 or S2) because the branches are only joined through an existing Client (C1). Clients does not route traffic from other Clients. +As an example, consider a new Client (C2) that is added to the second server (S4) in the right branch of a Wiretap network. This new Client will only be able to access routes via the right branch of the network (S3 and S4) and not the left branch (S1 or S2) because the branches are only joined through an existing Client (C1). Clients do not route traffic from other Clients. ``` ┌──────┐ From 83cff1483b515f4cbdabddf874c753b93cdac74f Mon Sep 17 00:00:00 2001 From: amerril Date: Mon, 21 Oct 2024 18:00:51 -0600 Subject: [PATCH 18/22] bold terminology --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 44e3a23..930ec51 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,9 @@ In this diagram, the Client has generated and installed WireGuard configuration # Terminology and Requirements -A Wiretap Server is any machine where a Wiretap binary is running the `serve` command. Servers receive and relay network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." +A **Wiretap Server** is any machine where a Wiretap binary is running the `serve` command. Servers receive and relay network traffic on behalf of Wiretap Clients, acting like a VPN "exit node." -A Wiretap Client is any machine running the [Wireguard](https://www.wireguard.com/) configurations necessary to send and receive network traffic through a Wiretap Server. It functions much like a client in a VPN connection. Clients are also able to reconfigure parts of the Wiretap network dynamically using the Wiretap binary. +A **Wiretap Client** is any machine running the [Wireguard](https://www.wireguard.com/) configurations necessary to send and receive network traffic through a Wiretap Server. It functions much like a client in a VPN connection. Clients are also able to reconfigure parts of the Wiretap network dynamically using the Wiretap binary. > [!IMPORTANT] > Unlike the typical use of "client" and "server" terms in networking, Wiretap's Client and Server terms have nothing to do with which machine listens for or initiates the initial connection. From 5b5d1dd194deab7705671909155122ee13da1858 Mon Sep 17 00:00:00 2001 From: amerril Date: Thu, 31 Oct 2024 12:02:44 -0600 Subject: [PATCH 19/22] full ToC --- README.md | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 930ec51..972acb5 100644 --- a/README.md +++ b/README.md @@ -15,14 +15,28 @@ In this diagram, the Client has generated and installed WireGuard configuration # Table of Contents -- [Terminology and Requirements](#Terminology-and-Requirements) -- [Quick Start](#Quick-Start) -- [Installation](#Installation) -- [How it Works](#How-it-Works) -- [Usage](#Usage) -- [Features](#Features) -- [Demo](#Demo) -- [Experimental](#Experimental) +- [Terminology and Requirements](#terminology-and-requirements) + - [Client System Requirements](#client-system-requirements) + - [Server System Requirements](#server-system-requirements) + - [Environment Requirements](#environment-requirements) +- [Quick Start](#quick-start) +- [Installation](#installation) +- [How it Works](#how-it-works) +- [Usage](#usage) + - [Configure](#configure) + - [Outbound Connections](#outbound-connections) + - [Simple Mode](#simple-mode) + - [Serve](#serve) + - [Add Server (Optional)](#add-server-optional) + - [Add Client (Optional)](#add-client-optional) + - [Expose (Port Forwarding)](#expose-port-forwarding) + - [List](#list) + - [Remove](#remove) +- [Features](#features) +- [Demo](#demo) +- [Experimental](#experimental) + - [TCP Tunneling](#tcp-tunneling) + - [Add Clients To Any Server](#add-clients-to-any-server) # Terminology and Requirements From 7aa943590342626d20754e0af8fdcd72bff7e1f2 Mon Sep 17 00:00:00 2001 From: amerril Date: Thu, 31 Oct 2024 12:12:37 -0600 Subject: [PATCH 20/22] fix example numbering to avoid 'C2' --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 972acb5..3c5ddf8 100644 --- a/README.md +++ b/README.md @@ -577,22 +577,22 @@ WIRETAP_RELAY_INTERFACE_PRIVATEKEY= WIRETAP_RELAY_PEER_PUBLICKEY= WIRE Clients can be attached to any Server in the network by using the `--server-address ` argument when running `wiretap add client`. This allows a Client on a different network than the first Client to still gain access to all of the Wiretap network's routes. However, the new Client will not be able to access any Servers that are part of a different chain connected to the first Client. -As an example, consider a new Client (C2) that is added to the second server (S4) in the right branch of a Wiretap network. This new Client will only be able to access routes via the right branch of the network (S3 and S4) and not the left branch (S1 or S2) because the branches are only joined through an existing Client (C1). Clients do not route traffic from other Clients. +As an example, consider a new Client (C1) that is added to the second server (S3) in the right branch of a Wiretap network. This new Client will only be able to access routes via the right branch of the network (S2 and S3) and not the left branch (S0 or S1) because the branches are only joined through an existing Client (C0). Clients do not route traffic from other Clients. ``` ┌──────┐ - │ C1 │ + │ C0 │ └┬────┬┘ │ │ ┌─────┴┐ ┌┴─────┐ - │ S1 │ │ S3 │ + │ S0 │ │ S2 │ └──┬───┘ └──┬───┘ │ │ ┌──┴───┐ ┌──┴───┐ - │ S2 │ │ S4 ◄───────┐ + │ S1 │ │ S3 ◄───────┐ └──────┘ └──────┘ │ ┌──┴───┐ - │ C2 │ + │ C1 │ └──────┘ ``` From db908550669096e8d89a5232d97f9455d5d831ed Mon Sep 17 00:00:00 2001 From: amerril Date: Thu, 31 Oct 2024 12:31:49 -0600 Subject: [PATCH 21/22] fix example IPs; add SOCAT example --- README.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 3c5ddf8..ce9b771 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ On the Client machine, run Wiretap's `configure` command to generate starting co Following the example in the diagram: ```bash -./wiretap configure --endpoint 7.1.1.3:1337 --routes 10.0.0.0/24 +./wiretap configure --endpoint 7.3.3.1:1337 --routes 10.0.0.0/24 ``` --- @@ -208,8 +208,8 @@ Endpoint = 172.17.0.2:51821 server config: wiretap_server.conf server command: -POSIX Shell: WIRETAP_RELAY_INTERFACE_PRIVATEKEY=WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y= WIRETAP_RELAY_INTERFACE_PORT=51820 WIRETAP_RELAY_PEER_PUBLICKEY=Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc= WIRETAP_RELAY_PEER_ENDPOINT=7.1.1.3:1337 WIRETAP_E2EE_INTERFACE_PRIVATEKEY=GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg= WIRETAP_E2EE_PEER_PUBLICKEY=cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve - PowerShell: $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_INTERFACE_PORT="51820"; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="7.1.1.3:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve +POSIX Shell: WIRETAP_RELAY_INTERFACE_PRIVATEKEY=WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y= WIRETAP_RELAY_INTERFACE_PORT=51820 WIRETAP_RELAY_PEER_PUBLICKEY=Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc= WIRETAP_RELAY_PEER_ENDPOINT=7.3.3.1:1337 WIRETAP_E2EE_INTERFACE_PRIVATEKEY=GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg= WIRETAP_E2EE_PEER_PUBLICKEY=cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve + PowerShell: $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_INTERFACE_PORT="51820"; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="7.3.3.1:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve Config File: ./wiretap serve -f wiretap_server.conf ``` @@ -252,7 +252,7 @@ $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs There are two other ways to pass arguments to the Server: 1. With the generated Server config file: `-f wiretap_server.conf` -2. The legacy method of passing command line arguments (`--endpoint 7.1.1.3:1337 ...`). Be aware that this method exposes the arguments to other users on the system. A compromised private key can be used to connect to the Client as a peer and/or decrypt traffic +2. The legacy method of passing command line arguments (`--endpoint 7.3.3.1:1337 ...`). Be aware that this method exposes the arguments to other users on the system. A compromised private key can be used to connect to the Client as a peer and/or decrypt traffic > [!NOTE] > The wiretap_server.conf file uses a notation unique to Wiretap. It cannot be used to start a server with `wg-quick` or other generic Wireguard tools. @@ -406,10 +406,10 @@ The `add client` command can be used to share access to the Wiretap network with > [!WARNING] > All servers must be deployed *before* adding additional clients. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. -Adding a new Client is very similar to the other commands. It will generate a `wiretap.conf` and `wiretap_relay.conf` for sharing. Make sure that all of the first-hop Servers (any Server directly attached to the original Client) can reach or be reached by the new Client or else the new Client won't have access to that chain of Servers. Once you get the endpoint information from whoever will be running the new Client (the IP and port they will listen on), run: +Adding a new Client is very similar to the other commands. It will generate a `wiretapX.conf` and `wiretap_relayX.conf` for sharing, where X is an incrementing number. Make sure that all of the first-hop Servers (any Server directly attached to the original Client) can reach or be reached by the new Client or else the new Client won't have access to that chain of Servers. Once you get the endpoint information from whoever will be running the new Client (the IP and port they will listen on), run: ```bash -./wiretap add client --endpoint 7.1.1.4:1337 --port 1337 +./wiretap add client --endpoint 7.3.3.2:1337 --port 1337 ``` --- @@ -473,9 +473,7 @@ You can expose a port on the Client to IPs in Wiretap's `routes` list by using t ./wiretap expose --local 80 --remote 8080 ``` -Now all existing Wiretap Servers will bind listeners on port 8080/tcp and proxy connections from that port to your local Client machine on port 80/tcp. By default this uses IPv6, so make sure any exposed services listening on the Client support IPv6 as well. - -To configure Wiretap to only use IPv4, use the `configure` command's `--disable-ipv6` option. +Now all existing Wiretap Servers will bind listeners on port 8080/tcp and proxy connections from that port to your local Client machine on port 80/tcp. By default this uses IPv6, so make sure any exposed services listening on the Client support IPv6 as well. To configure Wiretap to only use IPv4, use the `configure` command's `--disable-ipv6` option. > [!WARNING] > If a Wiretap server process exits or dies for any reason it will not remember ports it was previously exposing. You will need to re-expose any ports you configured with this command. @@ -570,6 +568,20 @@ Finally, run Wiretap on the remote server system, using the forwarded localhost WIRETAP_RELAY_INTERFACE_PRIVATEKEY= WIRETAP_RELAY_PEER_PUBLICKEY= WIRETAP_E2EE_INTERFACE_PRIVATEKEY= WIRETAP_E2EE_PEER_PUBLICKEY= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve --endpoint localhost:61820 ``` +Alternatively, if SOCAT is available on the Server and Client (or a machine that can be reached by them) you can use that to establish a UDP-over-TCP connection. + +On the Server: +``` +socat udp4-listen:61820,reuseaddr,fork tcp::61820 +``` + +On the Client: +``` +socat tcp4-listen:61820,reuseaddr,fork udp:localhost: +``` + +Then start the wiretap Server with the `--endpoint localhost:61820` argument. + ## Add Clients To Any Server > [!NOTE] From 0e30242095e1e1af89b58b4b98b1ed25f69300b6 Mon Sep 17 00:00:00 2001 From: amerril Date: Thu, 31 Oct 2024 12:49:36 -0600 Subject: [PATCH 22/22] add usage section for status command --- README.md | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index ce9b771..9816f42 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ In this diagram, the Client has generated and installed WireGuard configuration - [Outbound Connections](#outbound-connections) - [Simple Mode](#simple-mode) - [Serve](#serve) + - [Status](#status) - [Add Server (Optional)](#add-server-optional) - [Add Client (Optional)](#add-client-optional) - [Expose (Port Forwarding)](#expose-port-forwarding) @@ -134,6 +135,7 @@ Use "wiretap [command] --help" for more information about a command. The following commands are documented in this section: * [configure](#Configure) * [serve](#Serve) +* [status](#Status) * [add server](#Add-Server-Optional) * [add client](#Add-Client-Optional) * [expose](#Expose-Port-Forwarding) @@ -261,19 +263,9 @@ Confirm that the Relay interfaces on the Client and Server have successfully com Now the Client should be able to interact with the `routes` specified in the `configure` command! -## Add Server (Optional) - -
- -![Wiretap Add Server Arguments](media/Wiretap_Add_Server.svg) -
+## Status -The `add server` command is meant to extend the Wiretap network to reach new areas of a target network. At least one Client and Server must be configured and successfully deployed (i.e., with `configure`) before adding another Server. Servers can attach to any other Server *or* the Client itself. - -> [!WARNING] -> Due to the way new Clients are added to existing networks, all Servers must be deployed *before* adding additional Clients. Added Clients won't be able to access Servers deployed after they were added. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. - -You can view the state of the network and see API addresses with `./wiretap status` +Once the client configs have been imported and Wireguard is started, you can view the state of the network and see Server API addresses with `./wiretap status`. ```bash ./wiretap status @@ -301,9 +293,21 @@ You can view the state of the network and see API addresses with `./wiretap stat ╰─────────────────────╯ ``` -If you plan to attach a Server directly to the Client, the status command just confirms that everything is working as expected and the network layout is correct. If you want to attach a new Server to an existing Server you must also specify the existing Server's API address in your `add server` command using the `--server-address` argument; this API address **must** reference the same existing Server that the new Server will connect to via the `--endpoint` IP:port or else the new connection will fail. +## Add Server (Optional) + +
+ +![Wiretap Add Server Arguments](media/Wiretap_Add_Server.svg) +
+ +The `add server` command is meant to extend the Wiretap network to reach new areas of a target network. At least one Client and Server must be configured and successfully deployed (i.e., with `configure`) before adding another Server. Servers can attach to any other Server *or* the Client itself. + +> [!WARNING] +> Due to the way new Clients are added to existing networks, all Servers must be deployed *before* adding additional Clients. Added Clients won't be able to access Servers deployed after they were added. Additionally, if a Wiretap Server process exits or dies for any reason it will not remember any added Clients when you restart it. + +If you want to attach a new Server to an existing Server (rather than the Client) you must also specify the existing Server's API address in your `add server` command using the `--server-address` argument; this API address **must** reference the same existing Server that the new Server will connect to via the `--endpoint` IP:port or else the new connection will fail. You can view Server API addresses using the `status` command. -In this example, we will to the server with API address `::2`, which is listening on `10.0.0.2:51820`. This command will generate a configuration you can deploy to the new Server (through environment variables or a config file), just like with the `configure` command: +In this example, we will connect to the server that has API address `::2`, which is listening on `10.0.0.2:51820`: ```bash ./wiretap add server --server-address ::2 --endpoint 10.0.0.2:51820 --routes 10.0.1.0/24 @@ -351,9 +355,9 @@ Config File: ./wiretap serve -f wiretap_server_1.conf --- -The Client's E2EE configuration (`wiretap.conf`) will be modified to allow communication with the new Server, so you need to re-import it. For example, `sudo wg-quick down ./wiretap.conf && sudo wg-quick up ./wiretap.conf`. If you are attaching a new Server directly to the Client, the Relay interface will also need to be refreshed in the same way. +This command will modify the Client's E2EE configuration (`wiretap.conf`) to allow communication with the new Server, so you need to re-import it. For example, `sudo wg-quick down ./wiretap.conf && sudo wg-quick up ./wiretap.conf`. If you are attaching a new Server directly to the Client, the Relay config will also need to be refreshed in the same way. -Now you can use any of the `serve` command options to start Wiretap on the new Server. It will then join the Wiretap network by connecting to the existing Server. +Now you can use any of the `serve` command options to start Wiretap on the new Server, just like you did after running the `config` command. It will then join the Wiretap network by connecting to the existing Server. At this point the new routes should be usable! You can confirm that everything looks correct with `wiretap status`: