.Dd $Mdocdate$
.Dt RP 1
.Os
.Sh NAME
.Nm rp
.Nd high-level interface to rosenpass
.Sh SYNOPSIS
.Nm
.Op Ar explain
.Op Ar verbose
.Ar genkey Ar ... | Ar pubkey ... | Ar exchange ...
.Nm
.Op ...
.Ar genkey PRIVATE_KEYS_DIR
.Nm
.Op ...
.Ar pubkey Ar PRIVATE_KEYS_DIR Ar PUBLIC_KEYS_DIR
.Nm
.Op ...
.\" Splitting this across several lines
.Ar exchange Ar PRIVATE_KEYS_DIR
.Op dev <device>
.Op listen <ip>:<port>
.\" Because the peer argument is complicated, it would be heel to represent it
.\" in mdoc... Using an ugly hack instead, thereby losing semantic.
[peer PUBLIC_KEYS_DIR [endpoint <ip>:<port>] [persistent-keepalive <interval>]
[allowed-ips <ip1>/<cidr1>[,<ip2>/<cidr2>] ...]] ...
.Sh DESCRIPTION
The
.Nm
program
is used to build a VPN with WireGuard and Rosenpass.
.Pp
The optional
.Op explain
and
.Op verbose
options can be used to obtain further help or to enable a detailed view on the
operations, respectively.
.Ss COMMANDS
.Bl -tag -width Ds
.It Ar genkey Ar PRIVATE_KEYS_DIR
Creates a new directory with appropriate permissions and generates all the
necessary private keys required for a peer to participate in a rosenpass
connection.
.It Ar pubkey Ar PRIVATE_KEYS_DIR Ar PUBLIC_KEYS_DIR
Creates a fresh directory at
.Ar PUBLIC_KEYS_DIR ,
which contains the extracted public keys from the private keys generated by
.Ar genkey
and located inside
.Ar PRIVATE_KEYS_DIR .
.It Ar exchange Ar PRIVATE_KEYS_DIR [dev <device>] [listen <ip>:<port>] [PEERS]
Starts the VPN on interface
.Ar device ,
listening on the provided IP and port combination, allowing connections from
.Ar PEERS .
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
In this example, we will assume that the server has an interface bound to
192.168.0.1, that accepts incoming connections on port 9999/UDP for Rosenpass
and port 10000/UDP for WireGuard.
.Pp
To create a VPN connection, start by generating secret keys on both hosts.
.Bd -literal -offset indent
rp genkey server.rosenpass-secret
rp genkey client.rosenpass-secret
.Ed
.Pp
Extract the public keys:
.Bd -literal -offset indent
rp pubkey server.rosenpass-secret server.rosenpass-public
rp pubkey client.rosenpass-secret client.rosenpass-public
.Ed
.Pp
Copy the
.Qq -public
directories to the other peers and then start the VPN.
On the server:
.Bd -literal -offset indent
sudo rp exchange server.rosenpass-secret dev rosenpass0 listen 192.168.0.1:9999 \\
    peer client.rosenpass-public allowed-ips fe80::/64
.Ed
.Pp
On the client:
.Bd -literal -offset indent
sudo rp exchange client.rosenpass-secret dev rosenpass 0 \\
    peer server.rosenpass-public endpoint 192.168.0.1:9999 allowed-ips fe80::/64
.Ed
.Pp
Assign IP addresses:
.Bd -literal -offset indent
sudo ip a add fe80::1/64 dev rosenpass0 # Server
sudo ip a add fe80::2/64 dev rosenpass0 # Client
.Ed
.Pp
Test the connection by pinging the server on the client machine:
.Bd -literal -offset indent
ping fe80::1%rosenpass0 # Client
.Ed
.Pp
You can watch how rosenpass replaces the WireGuard PSK with the following:
.Bd -literal -offset indent
watch -n 0.2 'wg show all; wg show all preshared-keys'
.Ed
.Sh SEE ALSO
.Xr rosenpass 1 ,
.Xr wg 1
.Sh AUTHORS
Rosenpass was created by Karolin Varner, Benjamin Lipp, Wanja Zaeske,
Marei Peischl, Stephan Ajuvo, and Lisa Schmidt.
.Pp
This manual page was written by
.An Clara Engler
.Sh BUGS
The bugs are tracked at
.Lk https://github.com/rosenpass/rosenpass/issues .