                  Port of the Linux WireGuard kernel-driver

:Warning:

Although in principal functioning, the WireGuard port has not been exposed to a
sufficient amount of real-world testing, so far. Therefore, we strongly
recommend not to use it in any security-critical scenarios! There is no
guarantee that the port meets any of the security goals pursued by the
WireGuard protocol or other WireGuard implementations!

Functional description
======================

See wireguard.com for the basics on WireGuard itself and the 'wg' tool, that
was used as inspiration for the configuration format of the WireGuard port.
This section describes only the integration approach in Genode.

An instance of the WireGuard port requests two network sessions. One Uplink
session labelled "uplink_session" that acts like a regular network device
driver with the small particularity that it does not support ARP. It must be
connected only to the local peers of the private network. They communicate
plaintext with the Uplink session as if it were a network device connecting
them to the remote peers of the private network.

The other requested session is a NIC session labelled "nic_session" that must
be connected to the public network that acts as unsecure medium between the
different WireGuard instances that make up the private network. At this
session, the WireGuard port is a regular IPv4/UDP peer and DHCPv4 client and
transmits the private network packets encrypted and encapsulated in UDP.

Optionally, the WireGuard port might request an RTC session. This behavior is
described in more detail in [Global config attributes].

Configuration
=============

Here's a typical configuration of the WireGuard port:

!config | private_key: 0CtU34qsl97IGiYKSO4tMaF/SJvy04zzeQkhZEbZSk0=
!       | listen_port: 49001
!       | use_rtc:     false
!+ peer | public_key:    GrvyALPZ3PQ2AWM+ovxJqnxSqKpmTyqUui5jH+C8I0E=
!       | endpoint_ip:   10.1.2.1
!       | endpoint_port: 49002
!       | allowed_ip:    10.0.9.2/32
!-

Global config attributes
~~~~~~~~~~~~~~~~~~~~~~~~

The config attribute private_key contains the private key of the local
peer encoded with base64. The config attribute listen_port contains the
public-net port that the driver will listen at for incoming packets. The
config attribute use_rtc is optional and defaults to "false". It determines
whether the driver requests a real-time-clock session in order to provide real
packet timestamps. When set to "false", the driver will use the Timer-session
timestamp instead which starts from 0 each time the driver gets started.
In this mode, starting a driver in order to re-connect to an existing
WireGuard session wont work. Setting use_rtc to "true" however and providing
the driver with a working real-time clock results in the standard behavior
that can be observed with the Linux kernel driver.

Peers
~~~~~

There can be multiple peer sub-nodes in config, each representing a
remote peer at the WireGuard driver. The peer tags can be added and
removed dynamically which results in adding and removing peers at the driver.
The peer attribute public_key contains the public key of the remote
peer encoded with base64. The peer attribute allowed_ip contains the
private-net IPv4 address that the remote peer is allowed to use for
communicating to the local peer. The peer attributes enpoint_ip and
endpoint_port are optional and contain the initial public-net IPv4 address
respectively UDP port where the remote peer is expected at. These values may
change internally when the remote peer is found to be communicating from a
different endpoint.
