Job miragevpn-router
README
Skip to buildsMirageVPN library purely in OCaml
MirageVPN creates secure point-to-point or site-to-site connections in routed or bridged configurations and remote access facilities. It uses TLS to establish a (mutually) authenticated connection, over which material to derive the symmetric keys for packet encryption is exchanged. The protocol is compatible with OpenVPN™.
The goal of this project is to provide:
- A pure library implementing the protocol logic, and the OpenVPN™ config file format to enable interoperabilty and a smooth transition for existing deployments.
- MirageOS unikernels that act as OpenVPN™-compatible client and server.
We provide a handbook to guide you to install MirageVPN.
Our goal is not to implement the complete protocol, but rather a small useful subset with modern crypto and the latest key exchange methods, without deprecated or redundant features (embodying the philosophy of OCaml-tls). An initial draft of the network setup is depicted in the diagram below:
Since OpenVPN™ is not detailed in a protocol specificaton specified, apart from comments in the header files, we have written a specification document in Markdown, still work in progress.
Our configuration parser can be tested with an OpenVPN™ configuration file:
./_build/default/app/openvpn_config_parser.exe my.openvpn.conf
miragevpn_client_lwt
Unix client Included in this repository is a unix program that will connect to an
OpenVPN™ server, open a tun
interface, and tunnel packets between
the two.
Unix client on Linux
There are two ways to open tun
interfaces:
- Using a dynamically allocated interface (
dev tun
). In order to dynamically allocate atun
interface, the process will need privileges to do so. Either by running the client asroot
or with theCAP_NET_ADMIN
privilege. You would then adddev tun
to your configuration file. - Using a preallocated interface (
dev tunX
) This is the recommend configuration. To allocate such an interface fortun5
you can use this command:
You would then addsudo ip tuntap add mode tun user MYUSERNAME name tun5
dev tun5
to your configuration file.
dune build
# Bestowing the binary with CAP_NET_ADMIN if using dynamic tun allocation:
sudo setcap cap_net_admin=ep ./_build/default/app/miragevpn_client_lwt.exe
./_build/default/app/miragevpn_client_lwt.exe -v MY-CONFIG-FILE.CONF
OpenVPN™-compatible config parser
Our goal has been to implement a usable subset (as found in various real-world configuration files available to us during the implementation phase).
As far as possible we have strived to derive a representation that does not
permit ambiguity or conflicting options to be present in the parsed config.
Consult the type 'a k
declaration in openvpn_config.mli
for more
information.
This does not mean that conflicting options cannot be accepted from an on-disk
configuration file, but rather that such conflicts are explicitly handled in
the parser code (specifically in the resolve_conflict
function).
A notable difference from OpenVPN™ configuration parser is that we treat relative
paths in a configuration file to be relative to the configuration file
location, and not relative to the current working directory. OpenVPN™ supports
a --cd
argument, which we do not.
You can check compatibility with your configuration file by executing
dune build
./_build/default/app/openvpn_config_parser.exe MY-CONFIG-FILE.CONF
Discrepancies between MirageVPN and OpenVPN™
The "verify-x509-name name" in OpenVPN™ checks by default only the commonName of the subject in the X.509 certificate. MirageVPN validates the provided host against the set of hostnames in the certificate, namely the union of the commonName and the DNS entries in the SubjectAlternativeName extension.
When using a PKCS#12 file the certificates in it are not used to authenticate
the remote. OpenVPN™ will use the certificates if (and only if) no "ca" option
is specified. If it is desired to use the certificates from the PKCS#12 file
to authenticate the remote the certificates can be added with the "ca" option
by extracting the certificates with e.g. openssl pkcs12
.
For tls clients (as opposed to static key clients) we only support data channel
AEAD ciphers. This means the --auth
option is ignored for data channel
authentication for tls clients. For --tls-auth
it is still used to choose the
hmac used for the control channel while for --tls-crypt
and --tls-crypt-v2
the hmac is hardcoded (as per OpenVPN™).
If a "port" is specified, "lport" and "rport" may not be specified.
If a "remote" is specified with an IP address and no protocol (and thus no address family), and a default "proto" with an IP address family is specified, we ignore that default IP address family:
proto udpv6
remote 127.0.0.1
We consider this as "remote 127.0.0.1 udp4".
Funding
This project was funded in 2019 for six months by the German federal ministry for education and research via the Prototypefund - the amount was 47500 EUR.
In 2023, we received funding from European Union in the Next Generation Internet project (NGI assure, via NLnet. The scope was updating to the current protocol version (tls-crypt-v2 etc.), a QubesOS client, a server implementation, and more documentation. The amount was 57000 EUR. Learn more at the NLnet project page.
Builds
Back to readme- ☒ freebsd-14 2024-12-02 00:46:52Z Build failure: exited 125
- ☒ freebsd-14 2024-12-01 00:45:52Z Build failure: exited 125
- ☒ freebsd-14 2024-11-30 00:36:40Z Build failure: exited 125
- ☑ freebsd-14 2024-11-29 05:28:36Z ovpn-router.hvt
SHA256:2479bdd7b5d05a9be21e552def392890eb23e95c25a8a595a0399396d418a1d1
(7.14MB) - ☑ freebsd-14 2024-11-28 00:03:04Z ovpn-router.hvt
SHA256:ff93909afd694a8d0c24cce75a478f7f3aa30734f3b682e86c341efaac42bfab
(7.14MB) - ☑ freebsd-14 2024-11-15 00:20:58Z ovpn-router.hvt
SHA256:4946d640148c1d2601ea3207954eb5cbc0f2ea26c899c5ab49f13b8a97f67313
(7.14MB) - ☑ freebsd-14 2024-11-06 23:44:51Z ovpn-router.hvt
SHA256:3edfa090bed726efd9e3ff8a55440d4cbaeb0541761c31214f3ca764a4b201f1
(7.14MB) - ☑ freebsd-14 2024-10-23 23:32:29Z ovpn-router.hvt
SHA256:6a2a4c7487a0abc7b43e79d3f2eb819016414717cd7491fc56068182070c9dad
(7.14MB) - ☑ freebsd-14 2024-10-22 23:31:37Z ovpn-router.hvt
SHA256:f4a1bc73e71af6940dfff39345c26107611ed37efaf1b788afcac629b203c8f3
(7.14MB) - ☑ freebsd-14 2024-10-14 23:24:33Z ovpn-router.hvt
SHA256:a94fd95525260775f87da75a3a3c19bca5431d6b405d0a27d95c92a85910a0ee
(7.14MB) - ☑ freebsd-14 2024-10-13 23:23:41Z ovpn-router.hvt
SHA256:9685e94bae734dfb4527fcaa56c1e96d0276ebc5bb370b5c13ecaadb7ec0c583
(7.14MB) - ☑ freebsd-14 2024-10-10 23:20:56Z ovpn-router.hvt
SHA256:bb0b4473cf61f11182bdfc3d77e62d92c1baa94a1afa978c69c9bc442c68de0a
(7.14MB) - ☒ freebsd-14 2024-10-02 15:44:12Z Build failure: exited 1
- ☒ freebsd-14 2024-10-01 21:15:20Z Build failure: exited 1
- ☒ freebsd-14 2024-09-30 15:42:22Z Build failure: exited 1
- ☒ freebsd-14 2024-09-29 15:41:25Z Build failure: exited 1
- ☒ freebsd-14 2024-09-28 15:40:29Z Build failure: exited 1
- ☒ freebsd-14 2024-09-27 15:39:33Z Build failure: exited 1
- ☑ freebsd-14 2024-09-27 09:54:41Z ovpn-router.hvt
SHA256:1ce46bb4d6c272fdd720d56a721e15e6dc41290666afd26762aa43af93d2aaac
(7.34MB) - ☑ freebsd-14 2024-09-12 15:26:03Z ovpn-router.hvt
SHA256:5e0ddb31a742058442b929f59d097916cd11018a3902b5dfccfa47cdd6cffd2a
(7.34MB) - ☒ freebsd-14 2024-08-05 14:50:11Z Build failure: exited 1
- ☑ freebsd-14 2024-08-04 15:22:42Z ovpn-router.hvt
SHA256:6e9783e93b734dc94db4cb7728b7c73bd2669615fe813cb5c0843c0236be6f6a
(7.34MB) - ☑ freebsd-14 2024-07-20 14:35:09Z ovpn-router.hvt
SHA256:7e3ae8f3d9a39a397a3ac3104597b4a3c6c1055c9e844edff006d2009882cb44
(7.34MB)
Excluding failed builds here.