wireguard: README and config.xsd

Ref #4957

repos/dde_linux/src/app/wireguard/README

@@ -1,3 +1,4 @@
+                  Port of the Linux WireGuard kernel-driver
 
 :Warning:
 
@@ -6,3 +7,72 @@ 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" />
+!
+! </config>
+
+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.

repos/dde_linux/src/app/wireguard/config.xsd

@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+	<xs:include schemaLocation="base_types.xsd"/>
+	<xs:include schemaLocation="net_types.xsd"/>
+
+	<xs:element name="config">
+		<xs:complexType>
+			<xs:choice minOccurs="0" maxOccurs="unbounded">
+
+				<xs:element name="peer">
+					<xs:complexType>
+						<xs:attribute name="public_key" type="xs:string" />
+						<xs:attribute name="endpoint_ip" type="Ipv4_address" />
+						<xs:attribute name="endpoint_port" type="Port" />
+						<xs:attribute name="allowed_ip" type="Ipv4_address_prefix" />
+					</xs:complexType>
+				</xs:element><!-- peer -->
+
+			</xs:choice>
+			<xs:attribute name="private_key" type="xs:string"/>
+			<xs:attribute name="listen_port" type="Port" />
+			<xs:attribute name="use_rtc" type="Boolean" />
+		</xs:complexType>
+	</xs:element><!-- config -->
+
+</xs:schema>

repos/dde_linux/src/app/wireguard/target.mk

@@ -3,3 +3,5 @@ TARGET = wireguard
 SRC_CC += dummy.cc
 
 LIBS += wireguard
+
+CONFIG_XSD := config.xsd