rosenpass/doc/setup/multi_device_isolation.md

Multi Device Isolation

On supported systems (just Linux, state Feb. 2024), Rosenpass uses a so-called broker architecture where multiple operating system processes work together to negotiate a key using post quantum cryptography and then send it to WireGuard to run an actual VPN. This is similar to the sandboxes used by web browsers to prevent websites accessing the rest of the computer.

These processes communicate using what is called a "unix socket"; a special file that can be used by to processes to send data back and forth. There are tools to forward data from a unix socket one one host to a unix socket on another host. By using one of these tools, you can run most of Rosenpass' processes on one host while running just the process that forwards keys from Rosenpass to WireGuard on the device that establishes the WireGuard tunnel.

This type of setup can provide a very high degree of isolation. When set up correctly, a critical bug in the Rosenpass code can not affect the host running WireGuard and vice versa. Keep in mind though that for this goal to be reached, the method to connect both hosts must be sufficiently secured: If the WireGuard host is allowed to perform arbitrary commands on the Rosenpass host, then an attacker with access to the WireGuard device can also take over the Rosenpass device.

You can use the instructions from Unix Domain Socket Forwarding with OpenSSH to harden the connection between the two devices after following the instructions from this tutorial.

Instructions

In this manual, we are dealing with three hosts:

• The local peer: The local host running WireGuard
• The remote peer: The remote host we are connecting to.
• The the rosenpass device: The dedicated host running rosenpass. It connects with local peer to supply WireGuard with keys and it connects with remote peer to perform key exchanges.

Lets assume, that you are starting from a working Rosenpass setup on local peer and remote peer, running rosenpass and WireGuard on each host. Both setups use configuration files. We will move the rosenpass instance running on local peer to the rosenpass device in this tutorial.

Step 0: Setup Rosenpass

If you do not have a functioning rosenpass deployment on the local and remote peer at this point, you can create one by using the configuration files from the configuration-examples directory.

You will need to set up the WireGuard device manually using instructions for your linux distribution. You can use the tutorial on the arch wiki for reference.

Make sure to set a random pre-shared key during creation of the WireGuard setup on both hosts at startup. Random pre-shared keys can be generated by using wg genpks on each host.

For the broker based setup to work, you might have to assign the broker process the CAP_NET_ADMIN linux capability:

sudo setcap CAP_NET_ADMIN=+eip ./target/debug/rosenpass-wireguard-broker-privileged

Make sure the broker binaries are in your system path when starting rosenpass:

PATH="$PWD/target/debug:$PATH" ./target/debug/rosenpass exchange-config ./path/to/config/file.toml

You will also need to setup rosenpass on the rosenpass device.

Step 1: Verify that your rosenpass setup is working

Start rosenpass on both peers using the following command.

PATH="$PWD/target/debug:$PATH" rosenpass exchange-config ./path/to/config/file.toml

Now you can verify that rosenpass inserted a pre-shared key on both hosts:

wg show wgRpTest preshared-keys

The shell output will look similar to this:

tdnV/wa/0Uf8Nrm3cZkKXOm4atrOEPzv1+dvaG7p7y0=    5235LJ/ONgrO8XuxECtLPzGOyWSvuzHcexzcgoHubfs=

The first value is the peer's public key, the second in the pre-shared key. The pre-shared keys should match.

Step 2: Manually start the broker

Rosenpass starts the psk-broker internally by default. We are looking to manually start it instead.

On the local peer, first start the broker manually:

rm -fv broker.sock; PATH="target/debug" ./target/debug/rosenpass-wireguard-broker-socket-handler --listen-path broker.sock

Now you should update your configuration to make use of the created socket. Use the psk_broker configuration key. Your configuration will now look something like this:

public_key = "./path/to/pk"
secret_key = "./path/to/sk"
listen = ["192.168.0.20:9999"]
verbosity = "Verbose"
psk_broker = "./broker.sock"

[[peers]]
public_key = "./path/to/peer/pk"
device = "wgTesting"
peer = "tdnV/wa/0Uf8Nrm3cZkKXOm4atrOEPzv1+dvaG7p7y0="

Step 2: Forward the unix socket to the rosenpass device

OpenSSH socket forwarding can be used; on the local peer you can execute something like the following command:

ssh -vgMR path/to/rosenpass/broker.sock:./broker.sock -L user@rosenpass_device

Step 3: Start rosenpass on the rosenpass device

You may need to copy your configuration files to the rosenpass device:

scp ./path/to/config/file.toml ./path/to/peer/pk ./path/to/pk ./path/to/sk user@rosenpass_device:path/to/rosenpass/

Now you can start rosenpass on the rosenpass device:

PATH="$PWD/target/debug:$PATH" ./target/debug/rosenpass exchange-config ./path/to/config.toml

Step 4: Harden the setup

This tutorial is in a very rough state; it currently provides enough hints to advanced users to convey how the setup is supposed work. For a real production setup it needs to be adapted.

In particular, you can use the guide from from Unix Domain Socket Forwarding with OpenSSH to make sure neither the local peer nor the rosenpass device can execute arbitrary commands on each other. The socat tutorial used in this setup can be used to achieve a diversity of setups, such as forwarding the unix socket via a plain TCP socket without encryption to the rosenpass device, if a trusted network setup is used to connect the two. Other setups such as securing the connection using TLS or forwarding the connection via a serial connection can be achieved.

You should also make sure that the rosenpass secret key is at no point in time stored in the local peer, so if you followed this tutorial you might want to regenerate the keypair on the rosenpass device itself.