 |
OpenVPN 3 Core Library
|
|
OpenVPN 3 Core Library
|
OpenVPN 3 is a C++ class library that implements the functionality of an OpenVPN client, and is protocol-compatible with the OpenVPN 2.x branch.
OpenVPN 3 includes a minimal client wrapper (cli) that links in with the library and provides basic command line functionality.
OpenVPN 3 is currently used in production as the core of the OpenVPN Connect clients for iOS, Android, Linux, Windows, and Mac OS X.
NOTE: OpenVPN 3 does not currently implement server functionality.
OpenVPN 3 is organized as a C++ class library, and the API is defined in client/ovpncli.hpp.
A simple command-line wrapper for the API is provided in test/ovpncli/cli.cpp.
These instructions were tested on Ubuntu 22.04.
Install essential dependencies:
$ sudo apt install --no-install-recommends ca-certificates cmake g++ git iproute2 ninja-build pkg-config $ sudo apt install --no-install-recommends libasio-dev libcap-dev liblz4-dev libjsoncpp-dev libssl-dev libxxhash-dev
Potentially install optional dependencies:
$ sudo apt install --no-install-recommends libmbedtls-dev liblzo2-dev python3-dev swig
Clone the OpenVPN 3 source repo:
$ git clone https://github.com/OpenVPN/openvpn3.git
Build the OpenVPN 3 client wrapper (cli) with OpenSSL library:
$ cd openvpn3 && mkdir build && cd build $ cmake -GNinja .. $ cmake --build . $ ctest # Run Unit Tests
To use mbedTLS, use:
$ cmake -GNinja -DUSE_MBEDTLS=ON ..
Run OpenVPN 3 client:
$ sudo test/ovpncli/ovpncli myprofile.ovpn route-nopull
Options used:
myprofile.ovpn : OpenVPN config file (must have .ovpn extension)route-nopull : if you are connected via ssh, prevent ssh session lockoutovpn-dco is a kernel module which optimises data channel encryption and transport, providing better performance. The cli will detect when the kernel module is available and enable dco automatically (use --no-dco to disable this).
Download, build and install ovpn-dco:
$ sudo apt install make $ git clone https://github.com/OpenVPN/ovpn-dco.git $ cd ovpn-dco $ make && sudo make install $ sudo modprobe ovpn-dco
Install core dependencies:
$ sudo apt install libnl-genl-3-dev
Build cli with ovpn-dco support:
$ cd $O3/core/build $ cmake -DCLI_OVPNDCO=ON .. && cmake --build . $ sudo test/ovpncli/ovpncli [--no-dco] myprofile.ovpn
Options:
myprofile.ovpn : OpenVPN config file (must have .ovpn extension)--no-dco : disable data channel offload (optional)OpenVPN 3 should be built in a non-root macOS account. Make sure that Xcode is installed with optional command-line tools.
Create the directory ~/src:
$ mkdir -p ~/src
Clone the OpenVPN 3 repo:
$ cd ~/src $ git clone https://github.com/OpenVPN/openvpn3.git openvpn3
Install the dependencies:
Ensure that homebrew is set up.
$ brew install asio cmake jsoncpp lz4 openssl pkg-config xxhash
Now build the OpenVPN 3 client executable:
On a ARM64 based Mac:
$ cd ~/src/ $ mkdir build-openvpn3 $ cd build-openvpn3 $ cmake -DOPENSSL_ROOT_DIR=/opt/homebrew/opt/openssl -DCMAKE_PREFIX_PATH=/opt/homebrew ~/src/openvpn3 $ cmake --build .
For a build on a Intel based Mac:
$ cd ~/src/ $ mkdir build-openvpn3 $ cd build-openvpn3 $ cmake -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl -DCMAKE_PREFIX_PATH=/usr/local/opt ~/src/openvpn3 $ cmake --build .
This will build the OpenVPN 3 client library with a small client wrapper (ovpncli) and the unit tests.
These build scripts will create binaries with the same architecture as the host it is running on. The Mac OS X tuntap driver is not required, as OpenVPN 3 can use the integrated utun interface if available.
To view the client wrapper options:
$ ./test/ovpncli/ovpncli -h
To connect:
$ ./test/ovpncli/ovpncli client.ovpn
Prerequisites:
To build:
> git clone https://github.com/OpenVPN/openvpn3.git core && cd core > set VCPKG_ROOT=<path to vcpkg checkout> > cmake --preset win-amd64-release > cmake --build --preset win-amd64-release --target ovpncli
This build should work on both Windows and Linux.
Prerequisites:
To build:
$ git clone https://github.com/OpenVPN/openvpn3.git core && cd core $ export VCPKG_ROOT=<path to vcpkg checkout> $ cmake --preset mingw-x64-release $ cmake --build --preset mingw-x64-release --target ovpncli
The OpenVPN 3 core includes a stress/performance test of the OpenVPN protocol implementation. The test basically creates a virtualized lossy network between two OpenVPN protocol objects, triggers TLS negotiations between them, passes control/data channel messages, and measures the ability of the OpenVPN protocol objects to perform and remain in a valid state.
The OpenVPN protocol implementation that is being tested is here: openvpn/ssl/proto.hpp
The test code itself is here: test/unittests/test_proto.cpp It will be built and run as part of the unit test suite.
The unit tests are based on Google Test framework. To run unit tests, you need to install CMake and build Google Test.
Build and run tests on Linux:
$ cd $O3/core/build $ cmake --build . -- test/unittests/coreUnitTests $ make test
OpenVPN 3 is written in C++17 and developers who are moving from C to C++ should take some time to familiarize themselves with key C++ design patterns such as RAII.
OpenVPN 3 is designed as a class library, with an API that is essentially defined inside of namespace openvpn::ClientAPI with headers and implementation in [client](client) and header-only library files under [openvpn](openvpn).
The concise definition of the client API is essentially class openvpn::ClientAPI::OpenVPNClient in client/ovpncli.hpp with several important extensions to the API found in:
OpenVPN 3 includes a command-line reference client (cli) for testing the API. See test/ovpncli/cli.cpp.
The basic approach to building an OpenVPN 3 client is to define a client class that derives from openvpn::ClientAPI::OpenVPNClient, then provide implementations for callbacks including event and logging notifications:
class Client : public ClientAPI::OpenVPNClient
{
public:
virtual void event(const Event&) override { // events delivered here
...
}
virtual void log(const LogInfo&) override { // logging delivered here
...
}
...
};
To start the client, first create a openvpn::ProtoContext::ProtoConfig object and initialize it with the OpenVPN config file and other options:
ProtoContext::ProtoConfig config; config.content = <config_file_content_as_multiline_string>; ...
Next, create a client object and evaluate the configuration:
Client client;
ClientAPI::EvalConfig eval = client.eval_config(config);
if (eval.error)
throw ...;
Finally, in a new worker thread, start the connection:
ClientAPI::Status connect_status = client.connect();
Note that client.connect() will not return until the session has terminated.
The top layer of the OpenVPN 3 client is implemented in test/ovpncli/cli.cpp and openvpn/client/cliopt.hpp. Most of what this code does is marshalling the configuration and dispatching the higher-level objects that implement the OpenVPN client session.
class openvpn::ClientConnect in openvpn/client/cliconnect.hpp implements the top-level connection logic for an OpenVPN client connection. It is concerned with starting, stopping, pausing, and resuming OpenVPN client connections. It deals with retrying a connection and handles the connection timeout. It also deals with connection exceptions and understands the difference between an exception that should halt any further reconnection attempts (such as AUTH_FAILED), and other exceptions such as network errors that would justify a retry.
Some of the methods in the class (such as stop, pause, and reconnect) are often called by another thread that is controlling the connection, therefore thread-safe methods are provided where the thread-safe function posts a message to the actual connection thread.
In an OpenVPN client connection, the following object stack would be used:
OpenVPN 3 defines abstract base classes for Transport layer implementations in openvpn/transport/client/transbase.hpp.
Currently, transport layer implementations are provided for:
OpenVPN 3 defines abstract base classes for Tun layer implementations in openvpn/tun/client/tunbase.hpp.
There are two possible approaches to define a Tun layer implementation:
The OpenVPN protocol is implemented in class openvpn::ProtoContext in openvpn/ssl/proto.hpp.
The parsing and query of the OpenVPN config file is implemented by class openvpn::OptionList in openvpn/common/options.hpp.
Note that OpenVPN 3 always assumes an inline style of configuration, where all certs, keys, etc. are defined inline rather than through an external file reference.
For config files that do use external file references, class openvpn::ProfileMerge in openvpn/options/merge.hpp is provided to merge those external file references into an inline form.
The OpenVPN 3 client API, as defined by class openvpn::ClientAPI::OpenVPNClient in client/ovpncli.hpp, can be wrapped by the Swig tool to create bindings for other languages.
For example, OpenVPN Connect for Android creates a Java binding of the API using client/ovpncli.i.
When developing security software in C++, it's very important to take advantage of the language and OpenVPN library code to insulate code from the kinds of bugs that can introduce security vulnerabilities.
Here is a brief set of guidelines:
std::string rather than a char *.openvpn::Buffer, openvpn::ConstBuffer, openvpn::BufferAllocatedRc, or openvpn::BufferPtr object to provide managed access to the buffer, to protect against security bugs that arise when using raw buffer pointers. See openvpn/buffer/buffer.hpp for the OpenVPN Buffer classes.std::unique_ptr<> for non-shared objects and reference-counted smart pointers for shared objects. For shared-pointers, OpenVPN code should use the smart pointer classes defined in openvpn/common/rc.hpp. Please see the comments in this file for documentation.malloc or free. When allocating objects, use the C++ new operator and then immediately construct a smart pointer to reference the object: std::unique_ptr<MyObject> ptr = new MyObject(); ptr->method();
enum_dir() in openvpn/common/enumdir.hpp, a function that returns a list of files in a directory (Unix only) via a high-level string vector, while internally calling the low level libc methods opendir, readdir, and closedir. Notice how unique_ptr_del is used to wrap the DIR struct in a smart pointer with a custom deletion function.StrongRandomAPI::Ptr rng;
void set_rng(StrongRandomAPI::Ptr rng_arg) {
rng = std::move(rng_arg);
}
const.snprintf. Instead, use std::ostringstream or build the string using the + std::string operator: std::string format_reconnecting(const int n_seconds) {
return "Reconnecting in " + openvpn::to_string(n_seconds) + " seconds.";
}
or: std::string format_reconnecting(const int n_seconds) {
std::ostringstream os;
os << "Reconnecting in " << n_seconds << " seconds.";
return os.str();
}
inline attribute.OPENVPN_LOG() macro to log stuff. Don't use printf.goto. See OpenVPN's general exception classes and macros in openvpn/common/exception.hpp.pid_fn is deleted before scope exit: auto clean = Cleanup([pid_fn]() {
if (pid_fn)
::unlink(pid_fn);
});
fork), prepend :: to the symbol name, e.g.: struct dirent *e;
while ((e = ::readdir(dir.get())) != nullptr) {
...
}
nullptr instead of NULL.The OpenVPN 3 client core is designed to run in a single thread, with the UI or controller driving the OpenVPN API running in a different thread.
It's almost never necessary to create additional threads within the OpenVPN 3 client core.
See CONTRIBUTING.md.
See LICENSE.md.
1.9.8