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: peer-new-input 165 subset-of: peer 166 attributes: 167 - 168 name: id 169 - 170 name: remote-ipv4 171 - 172 name: remote-ipv6 173 - 174 name: remote-ipv6-scope-id 175 - 176 name: remote-port 177 - 178 name: socket 179 - 180 name: vpn-ipv4 181 - 182 name: vpn-ipv6 183 - 184 name: local-ipv4 185 - 186 name: local-ipv6 187 - 188 name: keepalive-interval 189 - 190 name: keepalive-timeout 191 - 192 name: peer-set-input 193 subset-of: peer 194 attributes: 195 - 196 name: id 197 - 198 name: remote-ipv4 199 - 200 name: remote-ipv6 201 - 202 name: remote-ipv6-scope-id 203 - 204 name: remote-port 205 - 206 name: vpn-ipv4 207 - 208 name: vpn-ipv6 209 - 210 name: local-ipv4 211 - 212 name: local-ipv6 213 - 214 name: keepalive-interval 215 - 216 name: keepalive-timeout 217 - 218 name: peer-del-input 219 subset-of: peer 220 attributes: 221 - 222 name: id 223 - 224 name: keyconf 225 attributes: 226 - 227 name: peer-id 228 type: u32 229 doc: >- 230 The unique ID of the peer in the device context. To be used to 231 identify peers during key operations 232 checks: 233 max: 0xFFFFFF 234 - 235 name: slot 236 type: u32 237 doc: The slot where the key should be stored 238 enum: key-slot 239 - 240 name: key-id 241 doc: >- 242 The unique ID of the key in the peer context. Used to fetch the 243 correct key upon decryption 244 type: u32 245 checks: 246 max: 7 247 - 248 name: cipher-alg 249 type: u32 250 doc: The cipher to be used when communicating with the peer 251 enum: cipher-alg 252 - 253 name: encrypt-dir 254 type: nest 255 doc: Key material for encrypt direction 256 nested-attributes: keydir 257 - 258 name: decrypt-dir 259 type: nest 260 doc: Key material for decrypt direction 261 nested-attributes: keydir 262 - 263 name: keydir 264 attributes: 265 - 266 name: cipher-key 267 type: binary 268 doc: The actual key to be used by the cipher 269 checks: 270 max-len: 256 271 - 272 name: nonce-tail 273 type: binary 274 doc: >- 275 Random nonce to be concatenated to the packet ID, in order to 276 obtain the actual cipher IV 277 checks: 278 exact-len: nonce-tail-size 279 280 - 281 name: keyconf-get 282 subset-of: keyconf 283 attributes: 284 - 285 name: peer-id 286 - 287 name: slot 288 - 289 name: key-id 290 - 291 name: cipher-alg 292 - 293 name: keyconf-swap-input 294 subset-of: keyconf 295 attributes: 296 - 297 name: peer-id 298 - 299 name: keyconf-del-input 300 subset-of: keyconf 301 attributes: 302 - 303 name: peer-id 304 - 305 name: slot 306 - 307 name: ovpn 308 attributes: 309 - 310 name: ifindex 311 type: u32 312 doc: Index of the ovpn interface to operate on 313 - 314 name: peer 315 type: nest 316 doc: >- 317 The peer object containing the attributed of interest for the specific 318 operation 319 nested-attributes: peer 320 - 321 name: keyconf 322 type: nest 323 doc: Peer specific cipher configuration 324 nested-attributes: keyconf 325 - 326 name: ovpn-peer-new-input 327 subset-of: ovpn 328 attributes: 329 - 330 name: ifindex 331 - 332 name: peer 333 nested-attributes: peer-new-input 334 - 335 name: ovpn-peer-set-input 336 subset-of: ovpn 337 attributes: 338 - 339 name: ifindex 340 - 341 name: peer 342 nested-attributes: peer-set-input 343 - 344 name: ovpn-peer-del-input 345 subset-of: ovpn 346 attributes: 347 - 348 name: ifindex 349 - 350 name: peer 351 nested-attributes: peer-del-input 352 - 353 name: ovpn-keyconf-get 354 subset-of: ovpn 355 attributes: 356 - 357 name: ifindex 358 - 359 name: keyconf 360 nested-attributes: keyconf-get 361 - 362 name: ovpn-keyconf-swap-input 363 subset-of: ovpn 364 attributes: 365 - 366 name: ifindex 367 - 368 name: keyconf 369 nested-attributes: keyconf-swap-input 370 - 371 name: ovpn-keyconf-del-input 372 subset-of: ovpn 373 attributes: 374 - 375 name: ifindex 376 - 377 name: keyconf 378 nested-attributes: keyconf-del-input 379 380operations: 381 list: 382 - 383 name: peer-new 384 attribute-set: ovpn-peer-new-input 385 flags: [admin-perm] 386 doc: Add a remote peer 387 do: 388 pre: ovpn-nl-pre-doit 389 post: ovpn-nl-post-doit 390 request: 391 attributes: 392 - ifindex 393 - peer 394 - 395 name: peer-set 396 attribute-set: ovpn-peer-set-input 397 flags: [admin-perm] 398 doc: modify a remote peer 399 do: 400 pre: ovpn-nl-pre-doit 401 post: ovpn-nl-post-doit 402 request: 403 attributes: 404 - ifindex 405 - peer 406 - 407 name: peer-get 408 attribute-set: ovpn 409 flags: [admin-perm] 410 doc: Retrieve data about existing remote peers (or a specific one) 411 do: 412 pre: ovpn-nl-pre-doit 413 post: ovpn-nl-post-doit 414 request: 415 attributes: 416 - ifindex 417 - peer 418 reply: 419 attributes: 420 - peer 421 dump: 422 request: 423 attributes: 424 - ifindex 425 reply: 426 attributes: 427 - peer 428 - 429 name: peer-del 430 attribute-set: ovpn-peer-del-input 431 flags: [admin-perm] 432 doc: Delete existing remote peer 433 do: 434 pre: ovpn-nl-pre-doit 435 post: ovpn-nl-post-doit 436 request: 437 attributes: 438 - ifindex 439 - peer 440 - 441 name: peer-del-ntf 442 doc: Notification about a peer being deleted 443 notify: peer-get 444 mcgrp: peers 445 446 - 447 name: key-new 448 attribute-set: ovpn 449 flags: [admin-perm] 450 doc: Add a cipher key for a specific peer 451 do: 452 pre: ovpn-nl-pre-doit 453 post: ovpn-nl-post-doit 454 request: 455 attributes: 456 - ifindex 457 - keyconf 458 - 459 name: key-get 460 attribute-set: ovpn-keyconf-get 461 flags: [admin-perm] 462 doc: Retrieve non-sensitive data about peer key and cipher 463 do: 464 pre: ovpn-nl-pre-doit 465 post: ovpn-nl-post-doit 466 request: 467 attributes: 468 - ifindex 469 - keyconf 470 reply: 471 attributes: 472 - keyconf 473 - 474 name: key-swap 475 attribute-set: ovpn-keyconf-swap-input 476 flags: [admin-perm] 477 doc: Swap primary and secondary session keys for a specific peer 478 do: 479 pre: ovpn-nl-pre-doit 480 post: ovpn-nl-post-doit 481 request: 482 attributes: 483 - ifindex 484 - keyconf 485 - 486 name: key-swap-ntf 487 notify: key-get 488 doc: >- 489 Notification about key having exhausted its IV space and requiring 490 renegotiation 491 mcgrp: peers 492 - 493 name: key-del 494 attribute-set: ovpn-keyconf-del-input 495 flags: [admin-perm] 496 doc: Delete cipher key for a specific peer 497 do: 498 pre: ovpn-nl-pre-doit 499 post: ovpn-nl-post-doit 500 request: 501 attributes: 502 - ifindex 503 - keyconf 504 505mcast-groups: 506 list: 507 - 508 name: peers 509