Commit 11fc5d
2025-02-27 13:09:54 Samuli Seppänen: Add DataChannelOffload/LinuxUAPI page| /dev/null .. DataChannelOffload/LinuxUAPI.md | |
| @@ 0,0 1,61 @@ | |
| + | # Data Channel Offload: the Linux Userspace API |
| + | |
| + | This page describes the API used by OpenVPN in userspace to control the ovpn-dco 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. |
| + | |
| + | Please also note that this API is currently in a development stage, meaning that it may still change and (possibly) break compatibility with userspace. |
| + | The goal is to freeze it and make it stable by the time ovpn-dco will be accepted upstream in the Linux kernel. |
| + | |
| + | ## Netlink |
| + | |
| + | The ovpn-dco 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](https://kernel.org/doc/html/next/userspace-api/netlink/intro.html). |
| + | |
| + | ovpn-dco has identified itself using the 'ovpn-dco' netlink family until version v0.1.20230206 and **has switched to the new 'ovpn-dco-v2' family since version v0.2.20230313**.\\ |
| + | This change was required because the two versions are not compatible with each other as a breaking change was implemented. |
| + | |
| + | **NOTE:** this breaking events are not expected to happen often, and actually we have planned for another similar change once ovpn-dco is (hopefully) merged with the upstream linux kernel codebase. |
| + | |
| + | ## API |
| + | |
| + | The ovpn-dco 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-dco 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_NEW_PEER |
| + | Inform ovpn-dco about a new peer. |
| + | |
| + | #### OVPN_CMD_SET_PEER |
| + | Configure peer parameters. |
| + | |
| + | #### OVPN_CMD_GET_PEER |
| + | 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_DEL_PEER |
| + | Delete peer from ovpn-dco 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_NEW_KEY |
| + | Add a new encryption/decryption key pair for a specific peer |
| + | |
| + | #### OVPN_CMD_SWAP_KEYS |
| + | Swap primary and secondary keys for a specific peer. |
| + | |
| + | #### OVPN_CMD_DEL_KEY |
| + | Erase the key from the given slot socket for a specific peer. |
| + | |
| + | |
| + | ### Events (from kernel to userspace) |
| + | |
| + | #### OVPN_CMD_DEL_PEER |
| + | Inform userspace that a peer has been deleted. |