{"id":13837259,"url":"https://github.com/ooni/minivpn","last_synced_at":"2025-10-25T13:20:37.765Z","repository":{"id":37810782,"uuid":"459614159","full_name":"ooni/minivpn","owner":"ooni","description":"A minimalistic OpenVPN implementation in Go","archived":false,"fork":false,"pushed_at":"2024-10-22T08:32:45.000Z","size":698,"stargazers_count":40,"open_issues_count":18,"forks_count":6,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-10-29T15:14:47.840Z","etag":null,"topics":["golang","openvpn-client"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ooni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-15T14:30:19.000Z","updated_at":"2024-10-22T08:31:40.000Z","dependencies_parsed_at":"2023-02-09T06:02:36.790Z","dependency_job_id":"70f0ce07-b343-45f4-8375-5161c00bbd0f","html_url":"https://github.com/ooni/minivpn","commit_stats":{"total_commits":274,"total_committers":3,"mean_commits":91.33333333333333,"dds":"0.11678832116788318","last_synced_commit":"5254d6892315db9d6c9b325d2575f1d7700828ee"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2Fminivpn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2Fminivpn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2Fminivpn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2Fminivpn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ooni","download_url":"https://codeload.github.com/ooni/minivpn/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230262831,"owners_count":18198938,"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":["golang","openvpn-client"],"created_at":"2024-08-04T15:01:04.815Z","updated_at":"2025-10-25T13:20:37.677Z","avatar_url":"https://github.com/ooni.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# minivpn\n\nA minimalistic implementation of the OpenVPN protocol in Go (client only).\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/ooni/gowl.svg)](https://pkg.go.dev/github.com/ooni/minivpn/vpn)\n![Build Status](https://github.com/ooni/minivpn/workflows/build/badge.svg)\n[![Go Report Card](https://goreportcard.com/badge/github.com/ooni/minivpn)](https://goreportcard.com/report/github.com/ooni/minivpn)\n\nThis implementation is intended for research purposes only. It has serious\nflaws, so please do **not** use it for any real-life situation where you need to\ntrust it with user data.\n\nThis is not a working implementation with all the properties that you need from\nsoftware that can effectively protect your privacy. If you arrived here looking\nfor such a thing, please use [misteriumnetwork/go-openvpn](https://github.com/mysteriumnetwork/go-openvpn) instead.\n\n\n## License\n\n```\nSPDX-License-Identifier: GPL-3.0-or-later\n```\n\n## OpenVPN Compatibility\n\n* Mode: Only `tls-client`.\n* Protocol: `UDPv4`, `TCPv4`.\n* Ciphers: `AES-128-CBC`, `AES-256-CBC`, `AES-128-GCM`, `AES-256-GCM`.\n* HMAC: `SHA1`, `SHA256`, `SHA512`.\n* Compression: `none`, `compress stub`, `comp-lzo no`.\n* tls-auth: `TODO`.\n* tls-crypt \u0026 [tls-crypt-v2](https://raw.githubusercontent.com/OpenVPN/openvpn/master/doc/tls-crypt-v2.txt): `TODO`.\n\n## Additional features\n\n### Obfuscation\n\n`obfs4` is supported. Add an additional entry in the config file, in this format:\n\n```\nproxy-obfs4 obfs4://RHOST:RPORT?cert=BASE64ENCODED_CERT\u0026iat-mode=0\n```\n\n## Configuration\n\nThe public constructor for `vpn.Client` allows you to instantiate a `Client` from a\ncorrectly initialized `Options` object.\n\nFor convenience, `minivpn` also understands how to parse a minimal subset of the\nconfiguration options that can be written in an openvpn config file.\n\n### Inline file support\n\nFollowing the configuration format in the reference implementation, `minivpn`\nallows including files in the main configuration file, but only for the ` ca`,\n`cert` and `key` options.\n\nEach inline file is started by the line `\u003coption\u003e` and ended by the line\n`\u003c/option\u003e`.\n\nHere is an example of an inline file usage:\n\n```\n\u003ccert\u003e\n-----BEGIN CERTIFICATE-----\n[...]\n-----END CERTIFICATE-----\n\u003c/cert\u003e\n```\n\n## Tests\n\nYou can run a `connect+ping` test against a given provider (but be aware that\nthere's very limited support for ciphersuites and compression). Place a config\nfile in `data/provider/config`. The [bootstrap script](https://github.com/ooni/minivpn/blob/main/scripts/bootstrap-provider)\ncan be useful.\n\nThen you can run:\n\n```\nmake test-ping\n```\n\n### Unit tests\n\nYou can run the short tests:\n\n```\ngo test -v --short ./...\n```\n\n### Integration tests\n\nYou will need `docker` installed to run the integration tests. They use a [fork\nof docker-openvpn](https://github.com/ooni/docker-openvpn) that allows us\nto configure some parameters at runtime (cipher and auth, for the time being). \n\n```\ncd tests/integration \u0026\u0026 go test -v .\n```\n\nThe `dockertest` package will take care of everything: it starts a container\nthat runs `openvpn`, binds it to port 1194, and exposes the config file for the\ntest client on `localhost:8080`.\n\nHowever, for debugging sometimes is useful to run the container on one shell:\n\n```\nmake integration-server\n```\n\nNow you can download the config file:\n\n```\ncurl localhost:8080/ \u003e config\n```\n\nThat config file is valid to use it with the `openvpn` client. Pro tip: launch\nit in a [separated namespace](https://github.com/slingamn/namespaced-openvpn)\nso not to mess with your global routes. `make netns-shell` will drop you in\na shell in the new namespace.\n\nTo be able to use that config file with the `minivpn` client, you need to\n[extract](https://github.com/ooni/minivpn/blob/main/tests/integration/extract.sh)\nthe different key blocks first. \n\nYou can download the config file, split it and run integration tests with:\n\n```\nmake test-local\n```\n\n## Limitations\n\nMany, but re-keying is maybe one of the first expected to limit the usefulness\nin the current state.\n\n## Security\n\n[7asecurity](https://7asecurity.com/) conducted an independent [whitebox security review against the minivpn implementation in August 2022](https://www.opentech.fund/results/security-safety-audits/minivpn-openvpn-go-client/).\nPlease refer to their [full pentest report](https://www.opentech.fund/documents/216/MIV-01_-_minivpn_-_OpenVPN_Go_Client_Audit_Report_FINAL.pdf) for further details.\n\nThanks to the Open Technology Fund for their support with this security audit.\n\n\n## Pointers\n\n* [Security Overview](https://community.openvpn.net/openvpn/wiki/SecurityOverview) in the OpenVPN wiki.\n* [doc_procotocol_overview.h](https://github.com/OpenVPN/openvpn/blob/master/doc/doxygen/doc_protocol_overview.h) in OpenVPN source code.\n* [OpenVPN page in Wireshark wiki](https://wiki.wireshark.org/OpenVPN), with some available `pcaps`.\n\n## References\n\n* https://github.com/OpenVPN/openvpn the reference implementation.\n* https://github.com/OpenVPN/openvpn3 the c++ class library for the client, protocol-compatible with the OpenVPN 2.x branch.\n* https://github.com/glacjay/govpn another go implementation\n* https://github.com/roburio/openvpn an ocaml implementation of a minimal subset of the protocol.\n* https://git.packetimpact.net/lvpn/ppyopenvpn a pure python implementation.\n\n## Acknowledgements\n\nBig thanks to people that wrote other implementations. This project started as\na learning exercise adapting `ppyopenvpn` to Go, and wouldn't have been\npossible without it.\n\nAnd to [Jason Donenfeld](https://www.jasondonenfeld.com/) for\nmaking [gVisor's netstack](https://gvisor.dev/docs/user_guide/networking/) more palatable.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooni%2Fminivpn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fooni%2Fminivpn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooni%2Fminivpn/lists"}