Data Channel Offload: the Linux Userspace API

This page describes the API used by OpenVPN in userspace to control the ovpn Linux kernel module.

A similar API exists for Windows and FreeBSD, but due to technical differences they need to be documented separately. This being said, their abstraction remain the same so the code in userspace needs very little adjustments in order to properly operate on all platforms.

Code implementing this API has been recently merged in the linux networking tree and it's on his way to linux-6.16. For this reason it should be considered fairly stable (breaking userspace is absolutely forbidden in the Linux kernel).

Netlink

The ovpn userspace API is based on the Netlink protocol. Netlink allows userspace and kernel modules to communicate by exchanging family specific messages normally crafted using the TLV (Type Length Value) format. This peculiarity allows developers to not break the API upon adding new messages or new attributes.

You can read more about Netlink here.

ovpn identifies itself using the 'ovpn' netlink family.

API

The ovpn Netlink API is composed by a set of commands aimed at managing the main objects living in kernel space: peers and keys.

Since the whole data channel processing happens in kernel space, ovpn needs to be aware of all the needed details so that it can operate independently from userspace.

Peer handling

The following commands are used to create, manage and destroy a peer in kernel space. Creating a peer is an essential step in order to enable sending and receiving data packets to/from it.

OVPN_CMD_PEER_NEW

Inform ovpn about a new peer.

OVPN_CMD_PEER_SET

Configure/change peer parameters.

OVPN_CMD_PEER_GET

Retrieve the whole list of connected peers with their status. It is possible to limit the retrieval to one peer only by specifying its ID.

OVPN_CMD_PEER_DEL

Delete peer from ovpn data structures.

Key handling

The following commands are used to create, swap and delete primary and secondary keys for a specific peer. This means that a peer must be created before adding a new key.\ A key comes with its own cipher, therefore, it is possible to use different ciphers for each peer and, possibly, switch cipher for a certain peer at runtime (not tested).

OVPN_CMD_KEY_NEW

Add a new encryption/decryption key pair for a specific peer.

OVPN_CMD_KEY_SWAP

Swap primary and secondary keys for a specific peer.

OVPN_CMD_KEY_DEL

Erase the key from the given slot for a specific peer.

Events (from kernel to userspace)

OVPN_CMD_PEER_DEL_NTF

Inform userspace that a peer has been deleted.

OVPN_CMD_KEY_SWAP_NTF

Inform userspace that the primary key has reached its maximum lifespan and must be substituted. No more traffic will be sent until a new key is provided.