Blame
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 1 | # Data Channel Offload: the Linux Userspace API |
| 2 | ||||
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 3 | This page describes the API used by OpenVPN in userspace to control the _ovpn_ Linux kernel module. |
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 4 | |
| 5 | A similar API exists for Windows and FreeBSD, but due to technical differences they need to be documented separately. |
|||
| 6 | 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. |
|||
| 7 | ||||
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 8 | Code implementing this API has been recently merged in the linux networking tree and it's on his way to **linux-6.16**. |
| 9 | For this reason it should be considered fairly stable (breaking userspace is absolutely forbidden in the Linux kernel). |
|||
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 10 | |
| 11 | ## Netlink |
|||
| 12 | ||||
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 13 | 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. |
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 14 | |
| 15 | You can read more about Netlink [here](https://kernel.org/doc/html/next/userspace-api/netlink/intro.html). |
|||
| 16 | ||||
| 16f713 | ordex | 2025-05-28 21:36:03 | 17 | _ovpn_ identifies itself using the 'ovpn' netlink family. |
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 18 | |
| 19 | ## API |
|||
| 20 | ||||
| 20cc8c | ordex | 2025-05-30 09:56:28 | 21 | The _ovpn_ Netlink API is composed by a set of commands aimed at managing the main objects living in kernel space: peers and keys. |
| 22 | ||||
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 23 | 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. |
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 24 | |
| 25 | ### Peer handling |
|||
| 26 | ||||
| 27 | 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. |
|||
| 28 | ||||
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 29 | #### OVPN_CMD_PEER_NEW |
| 30 | Inform _ovpn_ about a new peer. |
|||
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 31 | |
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 32 | #### OVPN_CMD_PEER_SET |
| 33 | Configure/change peer parameters. |
|||
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 34 | |
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 35 | #### OVPN_CMD_PEER_GET |
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 36 | 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. |
| 37 | ||||
| 871d98 | ordex | 2025-07-25 07:42:05 | 38 | When receiving this message, _ovpn_ will immediately send back a unicast reply (made up by one message per retrieved peer). |
| 39 | ||||
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 40 | #### OVPN_CMD_PEER_DEL |
| 41 | Delete peer from _ovpn_ data structures. |
|||
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 42 | |
| 43 | ### Key handling |
|||
| 44 | ||||
| e9ba45 | ordex | 2025-07-18 08:56:00 | 45 | 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. |
| 46 | ||||
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 47 | 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). |
| 48 | ||||
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 49 | #### OVPN_CMD_KEY_NEW |
| 50 | Add a new encryption/decryption key pair for a specific peer. |
|||
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 51 | |
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 52 | #### OVPN_CMD_KEY_SWAP |
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 53 | Swap primary and secondary keys for a specific peer. |
| 54 | ||||
| e9ba45 | ordex | 2025-07-18 08:56:00 | 55 | #### OVPN_CMD_KEY_GET |
| 56 | Retrieve the key attributes for a specific peer/slot. |
|||
| 57 | ||||
| 58 | No key material is actually exported. |
|||
| 59 | ||||
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 60 | #### OVPN_CMD_KEY_DEL |
| 61 | Erase the key from the given slot for a specific peer. |
|||
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 62 | |
| 63 | ||||
| 64 | ### Events (from kernel to userspace) |
|||
| 65 | ||||
| 871d98 | ordex | 2025-07-25 07:42:05 | 66 | Events are signaled to userspace by means of notification messages. |
| 67 | Notifications are asynchronous and sent as multicas messages to the _OVPN_NLGRP_PEERS_ group. |
|||
| 68 | They may be sent by _ovpn_ at any point in time, therefore it's up to userspace to be always ready |
|||
| 69 | to receive and process them. |
|||
| 70 | ||||
| 71 | Please note that a host system may have more than one _ovpn_ interface active at the same time and, |
|||
| 72 | while all notifications are delivered to the same multicast group, each receiver should check whether the |
|||
| 73 | ifindex associated with the notification is the one they are responsible for. |
|||
| 74 | ||||
| 75 | Potentially any software on the host system may listen for _ovpn_ notifications and react to them |
|||
| 76 | (i.e. by showing a pop-up to the user or by simply logging events). |
|||
| 77 | ||||
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 78 | #### OVPN_CMD_PEER_DEL_NTF |
| 11fc5d | Samuli Seppänen | 2025-02-27 13:09:54 | 79 | Inform userspace that a peer has been deleted. |
| dd3ce2 | ordex | 2025-05-28 21:35:36 | 80 | |
| 81 | #### OVPN_CMD_KEY_SWAP_NTF |
|||
| 82 | Inform userspace that the primary key has reached its maximum lifespan and must be substituted. |
|||
| 83 | No more traffic will be sent until a new key is provided. |