1# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) 2# 3# Author: Antonio Quartulli <antonio@openvpn.net> 4# 5# Copyright (c) 2024-2025, OpenVPN Inc. 6# 7--- 8name: ovpn 9 10protocol: genetlink 11 12doc: Netlink protocol to control OpenVPN network devices 13 14definitions: 15 - 16 type: const 17 name: nonce-tail-size 18 value: 8 19 - 20 type: enum 21 name: cipher-alg 22 entries: [none, aes-gcm, chacha20-poly1305] 23 - 24 type: enum 25 name: del-peer-reason 26 entries: 27 - teardown 28 - userspace 29 - expired 30 - transport-error 31 - transport-disconnect 32 - 33 type: enum 34 name: key-slot 35 entries: [primary, secondary] 36 37attribute-sets: 38 - 39 name: peer 40 attributes: 41 - 42 name: id 43 type: u32 44 doc: >- 45 The unique ID of the peer in the device context. To be used to 46 identify peers during operations for a specific device 47 checks: 48 max: 0xFFFFFF 49 - 50 name: remote-ipv4 51 type: u32 52 doc: The remote IPv4 address of the peer 53 byte-order: big-endian 54 display-hint: ipv4 55 - 56 name: remote-ipv6 57 type: binary 58 doc: The remote IPv6 address of the peer 59 display-hint: ipv6 60 checks: 61 exact-len: 16 62 - 63 name: remote-ipv6-scope-id 64 type: u32 65 doc: The scope id of the remote IPv6 address of the peer (RFC2553) 66 - 67 name: remote-port 68 type: u16 69 doc: The remote port of the peer 70 byte-order: big-endian 71 checks: 72 min: 1 73 - 74 name: socket 75 type: u32 76 doc: The socket to be used to communicate with the peer 77 - 78 name: socket-netnsid 79 type: s32 80 doc: The ID of the netns the socket assigned to this peer lives in 81 - 82 name: vpn-ipv4 83 type: u32 84 doc: The IPv4 address assigned to the peer by the server 85 byte-order: big-endian 86 display-hint: ipv4 87 - 88 name: vpn-ipv6 89 type: binary 90 doc: The IPv6 address assigned to the peer by the server 91 display-hint: ipv6 92 checks: 93 exact-len: 16 94 - 95 name: local-ipv4 96 type: u32 97 doc: The local IPv4 to be used to send packets to the peer (UDP only) 98 byte-order: big-endian 99 display-hint: ipv4 100 - 101 name: local-ipv6 102 type: binary 103 doc: The local IPv6 to be used to send packets to the peer (UDP only) 104 display-hint: ipv6 105 checks: 106 exact-len: 16 107 - 108 name: local-port 109 type: u16 110 doc: The local port to be used to send packets to the peer (UDP only) 111 byte-order: big-endian 112 checks: 113 min: 1 114 - 115 name: keepalive-interval 116 type: u32 117 doc: >- 118 The number of seconds after which a keep alive message is sent to the 119 peer 120 - 121 name: keepalive-timeout 122 type: u32 123 doc: >- 124 The number of seconds from the last activity after which the peer is 125 assumed dead 126 - 127 name: del-reason 128 type: u32 129 doc: The reason why a peer was deleted 130 enum: del-peer-reason 131 - 132 name: vpn-rx-bytes 133 type: uint 134 doc: Number of bytes received over the tunnel 135 - 136 name: vpn-tx-bytes 137 type: uint 138 doc: Number of bytes transmitted over the tunnel 139 - 140 name: vpn-rx-packets 141 type: uint 142 doc: Number of packets received over the tunnel 143 - 144 name: vpn-tx-packets 145 type: uint 146 doc: Number of packets transmitted over the tunnel 147 - 148 name: link-rx-bytes 149 type: uint 150 doc: Number of bytes received at the transport level 151 - 152 name: link-tx-bytes 153 type: uint 154 doc: Number of bytes transmitted at the transport level 155 - 156 name: link-rx-packets 157 type: uint 158 doc: Number of packets received at the transport level 159 - 160 name: link-tx-packets 161 type: uint 162 doc: Number of packets transmitted at the transport level 163 - 164 name: keyconf 165 attributes: 166 - 167 name: peer-id 168 type: u32 169 doc: >- 170 The unique ID of the peer in the device context. To be used to 171 identify peers during key operations 172 checks: 173 max: 0xFFFFFF 174 - 175 name: slot 176 type: u32 177 doc: The slot where the key should be stored 178 enum: key-slot 179 - 180 name: key-id 181 doc: >- 182 The unique ID of the key in the peer context. Used to fetch the 183 correct key upon decryption 184 type: u32 185 checks: 186 max: 7 187 - 188 name: cipher-alg 189 type: u32 190 doc: The cipher to be used when communicating with the peer 191 enum: cipher-alg 192 - 193 name: encrypt-dir 194 type: nest 195 doc: Key material for encrypt direction 196 nested-attributes: keydir 197 - 198 name: decrypt-dir 199 type: nest 200 doc: Key material for decrypt direction 201 nested-attributes: keydir 202 - 203 name: keydir 204 attributes: 205 - 206 name: cipher-key 207 type: binary 208 doc: The actual key to be used by the cipher 209 checks: 210 max-len: 256 211 - 212 name: nonce-tail 213 type: binary 214 doc: >- 215 Random nonce to be concatenated to the packet ID, in order to 216 obtain the actual cipher IV 217 checks: 218 exact-len: nonce-tail-size 219 - 220 name: ovpn 221 attributes: 222 - 223 name: ifindex 224 type: u32 225 doc: Index of the ovpn interface to operate on 226 - 227 name: peer 228 type: nest 229 doc: >- 230 The peer object containing the attributed of interest for the specific 231 operation 232 nested-attributes: peer 233 - 234 name: keyconf 235 type: nest 236 doc: Peer specific cipher configuration 237 nested-attributes: keyconf 238 239operations: 240 list: 241 - 242 name: peer-new 243 attribute-set: ovpn 244 flags: [admin-perm] 245 doc: Add a remote peer 246 do: 247 pre: ovpn-nl-pre-doit 248 post: ovpn-nl-post-doit 249 request: 250 attributes: 251 - ifindex 252 - peer 253 - 254 name: peer-set 255 attribute-set: ovpn 256 flags: [admin-perm] 257 doc: modify a remote peer 258 do: 259 pre: ovpn-nl-pre-doit 260 post: ovpn-nl-post-doit 261 request: 262 attributes: 263 - ifindex 264 - peer 265 - 266 name: peer-get 267 attribute-set: ovpn 268 flags: [admin-perm] 269 doc: Retrieve data about existing remote peers (or a specific one) 270 do: 271 pre: ovpn-nl-pre-doit 272 post: ovpn-nl-post-doit 273 request: 274 attributes: 275 - ifindex 276 - peer 277 reply: 278 attributes: 279 - peer 280 dump: 281 request: 282 attributes: 283 - ifindex 284 reply: 285 attributes: 286 - peer 287 - 288 name: peer-del 289 attribute-set: ovpn 290 flags: [admin-perm] 291 doc: Delete existing remote peer 292 do: 293 pre: ovpn-nl-pre-doit 294 post: ovpn-nl-post-doit 295 request: 296 attributes: 297 - ifindex 298 - peer 299 - 300 name: peer-del-ntf 301 doc: Notification about a peer being deleted 302 notify: peer-get 303 mcgrp: peers 304 305 - 306 name: key-new 307 attribute-set: ovpn 308 flags: [admin-perm] 309 doc: Add a cipher key for a specific peer 310 do: 311 pre: ovpn-nl-pre-doit 312 post: ovpn-nl-post-doit 313 request: 314 attributes: 315 - ifindex 316 - keyconf 317 - 318 name: key-get 319 attribute-set: ovpn 320 flags: [admin-perm] 321 doc: Retrieve non-sensitive data about peer key and cipher 322 do: 323 pre: ovpn-nl-pre-doit 324 post: ovpn-nl-post-doit 325 request: 326 attributes: 327 - ifindex 328 - keyconf 329 reply: 330 attributes: 331 - keyconf 332 - 333 name: key-swap 334 attribute-set: ovpn 335 flags: [admin-perm] 336 doc: Swap primary and secondary session keys for a specific peer 337 do: 338 pre: ovpn-nl-pre-doit 339 post: ovpn-nl-post-doit 340 request: 341 attributes: 342 - ifindex 343 - keyconf 344 - 345 name: key-swap-ntf 346 notify: key-get 347 doc: >- 348 Notification about key having exhausted its IV space and requiring 349 renegotiation 350 mcgrp: peers 351 - 352 name: key-del 353 attribute-set: ovpn 354 flags: [admin-perm] 355 doc: Delete cipher key for a specific peer 356 do: 357 pre: ovpn-nl-pre-doit 358 post: ovpn-nl-post-doit 359 request: 360 attributes: 361 - ifindex 362 - keyconf 363 364mcast-groups: 365 list: 366 - 367 name: peers 368