openvpn3

by OpenVPN

OpenVPN / openvpn3

OpenVPN 3 is a C++ class library that implements the functionality of an OpenVPN client, and is prot...

457 Stars 221 Forks Last release: Not found Other 3.1K Commits 33 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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.

.. contents:: Table of Contents

OpenVPN 3 Client API

OpenVPN 3 is organized as a C++ class library, and the API is defined in

_.

A simple command-line wrapper for the API is provided in

_.

Building the OpenVPN 3 client on Linux

These instructions were tested on Ubuntu 20.

Prepare directory structure: ::

$ sudo apt install g++ make libmbedtls-dev libssl-dev liblz4-dev cmake
$ export O3=~/O3 && mkdir $O3
$ export DEP_DIR=$O3/deps && mkdir $DEP_DIR
$ export DL=$O3/dl && mkdir $DL

Clone the OpenVPN 3 source repo: ::

$ cd $O3
$ git clone https://github.com/OpenVPN/openvpn3.git core

Build dependencies: ::

$ cd core/scripts/linux/
$ ./build-all

Build the OpenVPN 3 client wrapper (cli) with OpenSSL library: ::

$ cd $O3/core && mkdir build && cd build
$ cmake ..
$ cmake --build .

To use mbed TLS, use: ::

$ cmake -DUSE_MBEDTLS=on ..

Run OpenVPN 3 client: ::

$ sudo test/ovpncli/ovpncli myprofile.ovpn route-nopull

Options used:

  • :code:
    myprofile.ovpn
    : OpenVPN config file (must have .ovpn extension)
  • :code:
    route-nopull
    : if you are connected via ssh, prevent ssh session lockout

Using cli with ovpn-dco """""""""""""""""""""""

ovpn-dco is a kernel module which optimises data channel encryption and transport, providing better performance.

Download, build and install ovpn-dco: ::

$ cd $O3
$ 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 pkg-config libnl-genl-3-dev

Build cli with ovpn-dco support: ::

$ cd $O3/core/build
$ cmake -DCLI_OVPNDCO=on .. && make
$ sudo test/ovpncli/ovpncliovpndco --dco myprofile.ovpn

Options used:

  • :code:
    myprofile.ovpn
    : OpenVPN config file (must have .ovpn extension)
  • :code:
    --dco
    : enable data channel offload

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 https://github.com/OpenVPN/openvpn3.git 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 - https://github.com/chriskohlhoff/asio
  2. mbed TLS (2.3.0 or higher) - https://tls.mbed.org/
  3. LZ4 - https://github.com/Cyan4973/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: ::

$ DL=~/Downloads
$ 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 ASIO=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, mbed TLS, 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

Prerequisites:

  • Visual Studio 2019
  • CMake
  • vcpkg

Download and build dependencies: ::

> git clone https://github.com/Microsoft/vcpkg.git
> cd vcpkg
> bootstrap-vcpkg.bat
> vcpkg integrate install
> vcpkg install openssl-windows:x64-windows asio:x64-windows tap-windows6:x64-windows lz4:x64-windows gtest:x64-windows

Download and build core test client: ::

> git clone https://github.com/OpenVPN/openvpn3.git
> cmake -DCMAKE_TOOLCHAIN_FILE=\scripts\buildsystems\vcpkg.cmake -A x64 -B build openvpn3
> cmake --build build --config Release --target ovpncli

Testing

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:

_

The test code itself is here:

_

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 https://github.com/google/googletest.git
$ cd googletest
$ cmake . && cmake --build .

Building Google Test on Windows: ::

> git clone https://github.com/google/googletest.git
> 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 build.py ../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:

https://en.wikipedia.org/wiki/Resourceacquisitionis_initialization

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
_ and
header-only library files under 
_.

The consise definition of the client API is essentially

class OpenVPNClient
in
_ with several imporant extensions to
the API found in:

  • :code:

    class TunBuilderBase
    in
    _ —
    Provides an abstraction layer defining the tun interface,
    and is especially useful for interfacing with an OS-layer VPN API.
  • :code:

    class ExternalPKIBase
    in
    _ —
    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.
  • :code:

    class LogReceiver
    in
    _ —
    Provides an abstraction layer for the delivery of logging messages.

OpenVPN 3 includes a command-line reference client (

cli
) for testing the API. See
_.

The basic approach to building an OpenVPN 3 client is to define a client class that derives from :code:

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

ClientAPI::Config
object and initialize it with the OpenVPN config file and other options: ::
ClientAPI::Config config;
config.content = ;
...

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

client.connect()
will not return until the session has terminated.

Top Layer """""""""

The top layer of the OpenVPN 3 client is implemented in

_ and 
_.
Most of what this code does is marshalling the configuration and
dispatching the higher-level objects that implement the OpenVPN
client session.

Connection """"""""""

:code:

class ClientConnect
in
_
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. :code:
    class ClientConnect
    in
    _ —
    The top-layer object in an OpenVPN client connection.
  2. :code:
    class ClientProto::Session
    in
    _ —
    The OpenVPN client protocol object that subinstantiates the transport
    and tun layer objects.
  3. :code:
    class ProtoContext
    in
    _ —
    The core OpenVPN protocol implementation that is common to both
    client and server.
  4. :code:
    class ProtoStackBase
    in
    _ —
    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

_.

Currently, transport layer implementations are provided for:

  • UDP
    _
  • TCP
    _
  • HTTP Proxy
    _

Tun Layer """""""""

OpenVPN 3 defines abstract base classes for Tun layer implementations in

_.

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

    _
  2. Use an OS-specific model such as:

  • Linux
    _
  • Windows
    _
  • Mac OS X
    _

Protocol Layer """"""""""""""

The OpenVPN protocol is implemented in class ProtoContext in

_.

Options Processing """"""""""""""""""

The parsing and query of the OpenVPN config file is implemented by :code:

class OptionList
in
_.

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

class ProfileMerge
in
_
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 :code:

class OpenVPNClient
in
, can be wrapped by the
Swig tool to create bindings for other languages.

.. _Swig: http://www.swig.org/

For example, OpenVPN Connect for Android creates a Java binding of the API using

_.

Security

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

    std::string
    rather than a :code:
    char *
    .
  • When dealing with binary data or buffers, always try to use a :code:

    Buffer
    , :code:
    ConstBuffer
    , :code:
    BufferAllocated
    , or :code:
    BufferPtr
    object to provide managed access to the buffer, to protect against security bugs that arise when using raw buffer pointers. See
    _ for the OpenVPN :code:
    Buffer
    classes.
  • When it's necessary to have a pointer to an object, use :code:

    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
    _.  Please see the comments in
    this file for documentation.
  • Never use :code:

    malloc
    or :code:
    free
    . When allocating objects, use the C++ :code:
    new
    operator and then immediately construct a smart pointer to reference the object: ::

    std::unique_ptr ptr = new MyObject(); ptr->method();

  • When interfacing with C functions that deal with raw pointers, memory allocation, etc., consider wrapping the functionality in C++. For an example, see :code:

    enum_dir()
    in
    
    ,
    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
    :code:
    opendir
    , :code:
    readdir
    , and :code:
    closedir
    . Notice how :code:`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 :code:

    assert_crypto()
    on the RNG. This will throw an exception if the RNG is not crypto-grade: ::

    void setrng(RandomAPI::Ptr rngarg) { rngarg->assertcrypto(); rng = std::move(rng_arg); }

  • Any variable whose value is not expected to change should be declared :code:

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

  • When formatting strings, don't use :code:

    snprintf
    . Instead, use :code:
    std::ostringstream
    or build the string using the :code:
    +
    :code:
    std::string
    operator: ::

    std::string formatreconnecting(const int nseconds) { return "Reconnecting in " + openvpn::tostring(nseconds) + " seconds."; }

or: ::

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 :code:
    inline
    attribute.

Conventions """""""""""

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

    OPENVPN_LOG()
    macro to log stuff. Don't use :code:
    printf
    .
  • Don't call crypto/ssl libraries directly. Instead use the abstraction layers (

    _ and 
    _) that allow OpenVPN
    to link with different crypto/ssl libraries (such as OpenSSL
    or mbed TLS).
  • Use :code:

    RandomAPI
    as a wrapper for random number generators (
    _).
  • If you need to deal with configuration file options, see :code:

    class OptionList
    in
    _.
  • If you need to deal with time or time durations, use the classes under

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

    _.
  • In general, if you need a general-purpose library class or function, look under

    _.  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

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

    _.
  • 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 :code:

    goto
    . See OpenVPN's general exception classes and macros in
    _.
  • Use C++ destructors for automatic object cleanup, and so that thrown exceptions will not leak objects. Alternatively, use :code:

    Cleanup
    in
    _ when
    you need to specify a code block to execute prior to scope
    exit.  For example, ensure that the file :code:
    pid_fn
    is deleted before scope exit: ::

    auto clean = Cleanup(pid_fn { if (pidfn) ::unlink(pidfn); });

  • When calling global methods (such as libc :code:

    fork
    ), prepend :code:
    ::
    to the symbol name, e.g.: ::

    struct dirent *e; while ((e = ::readdir(dir.get())) != nullptr) { ... }

  • Use :code:

    nullptr
    instead of :code:
    NULL
    .

Threading """""""""

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.

Contributing

See

_.

License

See

_.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.