Skip to content
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.
C++ Shell HTML C Python Java Other
Branch: master
Clone or download
dsommers DCOTransport: Fix server side specific trunk handling
Commit 089aec0 pulled in a dependency for a very server specific
feature not normally needed in more basic implementations.  This
resulted in the code not being able to compile unless the advanced
implementation would be available.  This only happens when ENABLE_DCO is

Signed-off-by: David Sommerseth <>
Latest commit 69d72ed Aug 7, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis travis.yml: update environment Jul 19, 2019
client [OVPN-314] Add support for signalling SSO support via IV_SSO Jun 13, 2019
cmake Allow overriding DEP_DIR by environment variable May 13, 2019
deps win: enable building Windows client with OpenSSL Jun 5, 2019
doc OpenVPN Protocol extensions update. Jan 7, 2015
dockerfiles [OVPN3-223] build: add docker images Mar 28, 2018
javacli Implement allowing local LAN access Mar 12, 2019
mac xcode project: add liblz4 Apr 30, 2018
openvpn DCOTransport: Fix server side specific trunk handling Aug 7, 2019
scripts build: added CAP=1 -- build with libcap Jul 17, 2019
test Merge branch 'qa' Jul 19, 2019
vars Remove unsupported platforms from Android build Nov 7, 2018
win win: link OpenSSL dynamically Jun 20, 2019
.gitignore top-level .gitignore was missing a trailing newline Mar 9, 2018
.travis.yml travis.yml: update environment Jul 19, 2019
CLA.rst [OVPN3-140] Update company names in copyrights Dec 22, 2017
CMakeLists.txt Refactor dependencies to be in a cmake script May 13, 2019
CONTRIBUTING.rst Add Contributor License Agreement and OpenSSL linking exception Jan 10, 2017
COPYRIGHT.AGPLV3 [OVPN3-140] Relicense back to AGPLv3 Dec 22, 2017
LICENSE.rst [OVPN3-140] Relicense back to AGPLv3 Dec 22, 2017
README.rst README.rst: Make Windows-specific build steps up to date. Jul 17, 2019
VersionNumbering.rst Estblishing a stable branch Mar 9, 2018
appveyor.yml appveyor: make ReleaseOpenSSL default configuration Jun 20, 2019 [OVPN3-223] build: add docker images Mar 28, 2018


OpenVPN 3

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: As of 2017, OpenVPN 3 is primarily of interest to developers, as it does not yet replicate the full functionality of OpenVPN 2.x. In particular, server functionality is not yet implemented.

OpenVPN 3 Client API

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.

Building the OpenVPN 3 client on Linux

These instructions were tested on Ubuntu 16.

Get prerequisites to allow for either mbedTLS or OpenSSL linkage:

$ sudo apt-get install g++ make libmbedtls-dev libssl-dev liblz4-dev

Get Asio C++ library:

$ cd ~
$ git clone

Set environmental variable used by OpenVPN 3 build scripts:

$ export O3=~/ovpn3

Clone the OpenVPN 3 source repo:

$ mkdir ~/ovpn3
$ cd ~/ovpn3
$ git clone core

Build the OpenVPN 3 client wrapper (cli) with mbedTLS crypto/ssl library and LZ4 compression:

$ cd $O3/core/test/ovpncli
$ ECHO=1 PROF=linux ASIO_DIR=~/asio MTLS_SYS=1 LZ4_SYS=1 NOSSL=1 $O3/core/scripts/build cli

Or alternatively build with OpenSSL:

$ cd $O3/core/test/ovpncli
$ ECHO=1 PROF=linux ASIO_DIR=~/asio OPENSSL_SYS=1 LZ4_SYS=1 $O3/core/scripts/build cli

Run OpenVPN 3 client:

$ sudo ./cli -a -c yes myprofile.ovpn route-nopull

Options used:

-a             : use autologin sessions, if supported
-c yes         : negotiate LZ4 compression
myprofile.ovpn : OpenVPN config file (must have .ovpn extension)
route-nopull   : if you are connected via ssh, prevent ssh session lockout

Building the OpenVPN 3 client on Mac OS X

OpenVPN 3 should be built in a non-root Mac OS X account. Make sure that Xcode is installed with optional command-line tools. (These instructions have been tested with Xcode 5.1.1).

Create the directories ~/src and ~/src/mac:

$ mkdir -p ~/src/mac

Clone the OpenVPN 3 repo:

$ cd ~/src
$ mkdir ovpn3
$ cd ovpn3
$ git clone core

Export the shell variable O3 to point to the OpenVPN 3 top level directory:

export O3=~/src/ovpn3

Download source tarballs (.tar.gz or .tgz) for these dependency libraries into ~/Downloads

See the file $O3/core/deps/lib-versions for the expected version numbers of each dependency. If you want to use a different version of the library than listed here, you can edit this file.

  1. Asio —
  2. mbed TLS (2.3.0 or higher) —
  3. LZ4 —

For dependencies that are typically cloned from github vs. provided as a .tar.gz file, tools are provided to convert the github to a .tar.gz file. See "snapshot" scripts under $O3/core/deps

Note that while OpenSSL is listed in lib-versions, it is not required for Mac builds.

Build the dependencies:

$ OSX_ONLY=1 $O3/core/scripts/mac/build-all

Now build the OpenVPN 3 client executable:

$ cd $O3/core
$ . vars/vars-osx64
$ . vars/setpath
$ cd test/ovpncli
$ MTLS=1 LZ4=1 build cli

This will build the OpenVPN 3 client library with a small client wrapper (cli). It will also statically link in all external dependencies (Asio, mbedTLS, and LZ4), so cli may be distributed to other Macs and will run as a standalone executable.

These build scripts will create a x86_x64 Mac OS X executable, with a minimum deployment target of 10.8.x. 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:

$ ./cli -h

To connect:

$ ./cli client.ovpn

Building the OpenVPN 3 client on Windows


  • Visual Studio 2017
  • Python 2.7
  • Perl (for building openssl)

Clone the OpenVPN 3 source repo:

> c:\Temp>mkdir O3
> c:\Temp>cd O3
> c:\Temp\O3>git clone core

Add environment variable O3 with value c:\Temp\O3 and reopen commmand prompt.

Download and build dependencies:

> c:\Temp\O3>cd core\win
> c:\Temp\O3\core\win>set STATIC=1&& set DEBUG=1&& python

Now you can open project in Visual Studio. Project and solution files are located in O3\core\win directory.

You can also build the test client from command prompt:

> c:\Temp\O3\core\win>set STATIC=1&& set DEBUG=1&& python


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/ssl/proto.cpp

Build the test:

$ cd ovpn3/core/test/ssl
$ ECHO=1 PROF=linux ASIO_DIR=~/asio MTLS_SYS=1 NOSSL=1 $O3/core/scripts/build proto

Run the test:

$ time ./proto
*** app bytes=72777936 net_bytes=122972447 data_bytes=415892854 prog=0000216599/0000216598 D=12700/600/12700/600 N=109/109 SH=17400/15300 HE=0/0

real  0m15.813s
user  0m15.800s
sys   0m0.004s

The OpenVPN 3 core also includes unit tests, which are based on Google Test framework. To run unit tests, you need to install CMake and build Google Test.

Building Google Test on Linux:

$ git clone
$ cd googletest
$ cmake . && cmake --build .

Building Google Test on Windows:

> git clone
> cd googletest
> cmake -G "Visual Studio 14 2015 Win64" .
> cmake --build .

After Google Test is built you are ready to build and run unit tests.

Build and run tests on Linux:

$ cd ovpn3/core/test/unittests
$ GTEST_DIR=~/googletest ECHO=1 PROF=linux ASIO_DIR=~/asio MTLS_SYS=1 LZ4_SYS=1 NOSSL=1 $O3/core/scripts/build test_log
$ ./test_log

Build and run tests on Windows:

$ cd ovpn3/core/win
$ python ../test/unittests/test_log.cpp unittest
$ test_log.exe

Developer Guide

OpenVPN 3 is written in C++11 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 Client Core

OpenVPN 3 is designed as a class library, with an API that is essentially defined inside of namespace ClientAPI with headers and implementation in client and header-only library files under openvpn.

The consise definition of the client API is essentially class OpenVPNClient in client/ovpncli.hpp with several imporant extensions to the API found in:

  • class TunBuilderBase in openvpn/tun/builder/base.hpp — Provides an abstraction layer defining the tun interface, and is especially useful for interfacing with an OS-layer VPN API.
  • class ExternalPKIBase in openvpn/pki/epkibase.hpp — Provides a callback for external private key operations, and is useful for interfacing with an OS-layer Keychain such as the Keychain on iOS, Mac OS X, and Android, and the Crypto API on Windows.
  • class LogReceiver in client/ovpncli.hpp — Provides an abstraction layer for the delivery of logging messages.

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 ClientAPI::OpenVPNClient, then provide implementations for callbacks including event and logging notifications:

class Client : public ClientAPI::OpenVPNClient
      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 ClientAPI::Config object and initialize it with the OpenVPN config file and other options:

ClientAPI::Config 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.

Top Layer

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 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:

  1. class ClientConnect in openvpn/client/cliconnect.hpp — The top-layer object in an OpenVPN client connection.
  2. class ClientProto::Session in openvpn/client/cliproto.hpp — The OpenVPN client protocol object that subinstantiates the transport and tun layer objects.
  3. class ProtoContext in openvpn/ssl/proto.hpp — The core OpenVPN protocol implementation that is common to both client and server.
  4. class ProtoStackBase<Packet> in openvpn/ssl/protostack.hpp — The bottom-layer class that implements the basic functionality of tunneling a protocol over a reliable or unreliable transport layer, but isn't specific to OpenVPN per-se.

Transport Layer

OpenVPN 3 defines abstract base classes for Transport layer implementations in openvpn/transport/client/transbase.hpp.

Currently, transport layer implementations are provided for:

Tun Layer

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:

  1. Use a VPN API-centric model (such as for Android or iOS). These models derive from class TunBuilderBase in openvpn/tun/builder/base.hpp

  2. Use an OS-specific model such as:

Protocol Layer

The OpenVPN protocol is implemented in class ProtoContext in openvpn/ssl/proto.hpp.

Options Processing

The parsing and query of the OpenVPN config file is implemented by class 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 ProfileMerge in openvpn/options/merge.hpp is provided to merge those external file references into an inline form.

Calling the Client API from other languages

The OpenVPN 3 client API, as defined by class 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 javacli/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:

  • When dealing with strings, use a std::string rather than a char *.

  • When dealing with binary data or buffers, always try to use a Buffer, ConstBuffer, BufferAllocated, or 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.

  • When it's necessary to have a pointer to an object, use 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.

  • Never use 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();
  • When interfacing with C functions that deal with raw pointers, memory allocation, etc., consider wrapping the functionality in C++. For an example, see 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.

  • When grabbing random entropy that is to be used for cryptographic purposes (i.e. for keys, tokens, etc.), always ensure that the RNG is crypto-grade by calling assert_crypto() on the RNG. This will throw an exception if the RNG is not crypto-grade:

    void set_rng(RandomAPI::Ptr rng_arg) {
      rng = std::move(rng_arg);
  • Any variable whose value is not expected to change should be declared const.

  • Don't use non-const global or static variables unless absolutely necessary.

  • When formatting strings, don't use 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.";


    std::string format_reconnecting(const int n_seconds) {
      std::ostringstream os;
      os << "Reconnecting in " << n_seconds << " seconds.";
      return os.str();
  • OpenVPN 3 is a "header-only" library, therefore all free functions outside of classes should have the inline attribute.


  • Use the Asio library for I/O and timers. Don't deal with sockets directly.

  • Never block. If you need to wait for something, use Asio timers or sockets.

  • Use the OPENVPN_LOG() macro to log stuff. Don't use printf.

  • Don't call crypto/ssl libraries directly. Instead use the abstraction layers (openvpn/crypto and openvpn/ssl) that allow OpenVPN to link with different crypto/ssl libraries (such as OpenSSL or mbed TLS).

  • Use RandomAPI as a wrapper for random number generators (openvpn/random/randapi.hpp).

  • If you need to deal with configuration file options, see class OptionList in openvpn/common/options.hpp.

  • If you need to deal with time or time durations, use the classes under openvpn/time.

  • If you need to deal with IP addresses, see the comprehensive classes under openvpn/addr.

  • In general, if you need a general-purpose library class or function, look under openvpn/common. Chances are good that it's already been implemented.

  • The OpenVPN 3 approach to errors is to count them, rather than unconditionally log them. If you need to add a new error counter, see openvpn/error/error.hpp.

  • If you need to create a new event type which can be transmitted as a notification back to the client API user, see openvpn/client/clievent.hpp.

  • Raw pointers or references can be okay when used by an object to point back to its parent (or container), if you can guarantee that the object will not outlive its parent. Backreferences to a parent object is also a common use case for weak pointers.

  • Use C++ exceptions for error handling and as an alternative to goto. See OpenVPN's general exception classes and macros in openvpn/common/exception.hpp.

  • Use C++ destructors for automatic object cleanup, and so that thrown exceptions will not leak objects. Alternatively, use Cleanup in openvpn/common/cleanup.hpp when you need to specify a code block to execute prior to scope exit. For example, ensure that the file pid_fn is deleted before scope exit:

    auto clean = Cleanup([pid_fn]() {
      if (pid_fn)
  • When calling global methods (such as libc fork), prepend "::" to the symbol name, e.g.:

    struct dirent *e;
    while ((e = ::readdir(dir.get())) != nullptr) {
  • Use 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 LICENSE.rst.

You can’t perform that action at this time.