{"id":28612268,"url":"https://github.com/roburio/openvpn","last_synced_at":"2025-06-12T00:03:58.792Z","repository":{"id":52220164,"uuid":"215282811","full_name":"robur-coop/miragevpn","owner":"robur-coop","description":"An opinionated implementation of the OpenVPN protocol","archived":false,"fork":false,"pushed_at":"2025-03-10T10:28:30.000Z","size":2692,"stargazers_count":79,"open_issues_count":26,"forks_count":10,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-06-10T01:48:05.073Z","etag":null,"topics":["mirageos","ocaml","openvpn","openvpn-client","openvpn-server","unikernel","vpn"],"latest_commit_sha":null,"homepage":"","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robur-coop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-15T11:34:36.000Z","updated_at":"2025-03-10T10:28:32.000Z","dependencies_parsed_at":"2023-10-03T14:05:45.969Z","dependency_job_id":"953d321a-c940-4a63-8546-db1e60afe970","html_url":"https://github.com/robur-coop/miragevpn","commit_stats":null,"previous_names":["roburio/miragevpn","roburio/openvpn","robur-coop/miragevpn"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/robur-coop/miragevpn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiragevpn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiragevpn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiragevpn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiragevpn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robur-coop","download_url":"https://codeload.github.com/robur-coop/miragevpn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiragevpn/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259368018,"owners_count":22846822,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mirageos","ocaml","openvpn","openvpn-client","openvpn-server","unikernel","vpn"],"created_at":"2025-06-12T00:02:03.069Z","updated_at":"2025-06-12T00:03:58.782Z","avatar_url":"https://github.com/robur-coop.png","language":"OCaml","funding_links":[],"categories":["OCaml"],"sub_categories":[],"readme":"## MirageVPN library purely in OCaml\n\nMirageVPN creates secure point-to-point or site-to-site connections in routed or bridged configurations and remote access facilities.\nIt uses TLS to establish a (mutually) authenticated connection, over which material to derive the symmetric keys for packet encryption is exchanged.\nThe protocol is compatible with OpenVPN™.\n\nThe goal of this project is to provide:\n- A pure library implementing the protocol logic, and the OpenVPN™ config file format to enable interoperabilty and a smooth transition for existing deployments.\n- [MirageOS](https://mirage.io) unikernels that act as OpenVPN™-compatible client and server.\n\nWe provide a [handbook](https://robur-coop.github.io/miragevpn-handbook/) to guide you to install MirageVPN.\n\nOur 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\n(embodying the philosophy of [OCaml-tls](https://github.com/mirleft/ocaml-tls)).  An initial draft of the network setup is depicted in the diagram below:\n\n![diagram](/diagrams/multi-stack.svg)\n\nSince OpenVPN™ is not detailed in a protocol specificaton specified, apart from comments in the header files, we have written a [specification document](https://github.com/robur-coop/miragevpn-spec) in Markdown, still work in progress.\n\nOur configuration parser can be tested with an OpenVPN™ configuration file:\n\n  - `./_build/default/app/openvpn_config_parser.exe my.openvpn.conf`\n\n# Unix client `miragevpn_client_lwt`\n\nIncluded in this repository is a unix program that will connect to an\nOpenVPN™ server, open a `tun` interface, and tunnel packets between\nthe two.\n\n## Unix client on Linux\n\nThere are two ways to open `tun` interfaces:\n1) Using a dynamically allocated interface (`dev tun`).\n   In order to dynamically allocate a `tun` interface, the process will need\n   privileges to do so. Either by running the client as `root` or with\n   the `CAP_NET_ADMIN` privilege.\n   You would then add `dev tun` to your configuration file.\n2) Using a preallocated interface (`dev tunX`)\n   This is the recommend configuration.\n   To allocate such an interface for `tun5` you can use this command:\n   ```shell\n   sudo ip tuntap add mode tun user MYUSERNAME name tun5\n   ```\n   You would then add `dev tun5` to your configuration file.\n\n```shell\ndune build\n\n# Bestowing the binary with CAP_NET_ADMIN if using dynamic tun allocation:\nsudo setcap cap_net_admin=ep ./_build/default/app/miragevpn_client_lwt.exe\n\n./_build/default/app/miragevpn_client_lwt.exe -v MY-CONFIG-FILE.CONF\n```\n\n# OpenVPN™-compatible config parser\n\nOur goal has been to implement a usable subset (as found in various\n real-world configuration files available to us during the implementation\n phase).\n\nAs far as possible we have strived to derive a representation that does not\n permit ambiguity or conflicting options to be present in the parsed config.\nConsult the `type 'a k` declaration in `openvpn_config.mli` for more\n information.\n\nThis does not mean that conflicting options cannot be accepted from an on-disk\n configuration file, but rather that such conflicts are explicitly handled in\n the parser code (specifically in the `resolve_conflict` function).\n\nA notable difference from OpenVPN™ configuration parser is that we treat relative\n paths in a configuration file to be relative to the configuration file\n location, and not relative to the current working directory. OpenVPN™ supports\n a `--cd` argument, which we do not.\n\nYou can check compatibility with your configuration file by executing\n```shell\ndune build\n./_build/default/app/openvpn_config_parser.exe MY-CONFIG-FILE.CONF\n```\n\n## Discrepancies between MirageVPN and OpenVPN™\n\nThe \"verify-x509-name \u003chost\u003e name\" in OpenVPN™ checks by default only the\ncommonName of the subject in the X.509 certificate. MirageVPN validates the\nprovided host against the set of hostnames in the certificate, namely the union\nof the commonName and the DNS entries in the SubjectAlternativeName extension.\n\nWhen using a PKCS#12 file the certificates in it are not used to authenticate\nthe remote. OpenVPN™ will use the certificates if (and only if) no \"ca\" option\nis specified. If it is desired to use the certificates from the PKCS#12 file\nto authenticate the remote the certificates can be added with the \"ca\" option\nby extracting the certificates with e.g. `openssl pkcs12`.\n\nFor tls clients (as opposed to static key clients) we only support data channel\nAEAD ciphers. This means the `--auth` option is ignored for data channel\nauthentication for tls clients. For `--tls-auth` it is still used to choose the\nhmac used for the control channel while for `--tls-crypt` and `--tls-crypt-v2`\nthe hmac is hardcoded (as per OpenVPN™).\n\nIf a \"port\" is specified, \"lport\" and \"rport\" may not be specified.\n\nIf a \"remote\" is specified with an IP address and no protocol (and thus no\naddress family), and a default \"proto\" with an IP address family is specified,\nwe ignore that default IP address family:\n```\nproto udpv6\nremote 127.0.0.1\n```\nWe consider this as \"remote 127.0.0.1 \u003cport\u003e udp4\".\n\n## Funding\n\nThis project was funded in 2019 for six months by the [German federal ministry for education and research](https://www.bmbf.de) via the [Prototypefund](https://prototypefund.de) - the amount was 47500 EUR.\n\nIn 2023, we received funding from European Union in the Next Generation Internet project ([NGI assure](https://www.assure.ngi.eu/), via [NLnet](https://nlnet.nl). 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](https://nlnet.nl/project/MirageVPN).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froburio%2Fopenvpn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froburio%2Fopenvpn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froburio%2Fopenvpn/lists"}