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 Also used to match packets received from this peer. 48 checks: 49 max: 0xFFFFFF 50 - 51 name: remote-ipv4 52 type: u32 53 doc: The remote IPv4 address of the peer 54 byte-order: big-endian 55 display-hint: ipv4 56 - 57 name: remote-ipv6 58 type: binary 59 doc: The remote IPv6 address of the peer 60 display-hint: ipv6 61 checks: 62 exact-len: 16 63 - 64 name: remote-ipv6-scope-id 65 type: u32 66 doc: The scope id of the remote IPv6 address of the peer (RFC2553) 67 - 68 name: remote-port 69 type: u16 70 doc: The remote port of the peer 71 byte-order: big-endian 72 checks: 73 min: 1 74 - 75 name: socket 76 type: u32 77 doc: The socket to be used to communicate with the peer 78 - 79 name: socket-netnsid 80 type: s32 81 doc: The ID of the netns the socket assigned to this peer lives in 82 - 83 name: vpn-ipv4 84 type: u32 85 doc: The IPv4 address assigned to the peer by the server 86 byte-order: big-endian 87 display-hint: ipv4 88 - 89 name: vpn-ipv6 90 type: binary 91 doc: The IPv6 address assigned to the peer by the server 92 display-hint: ipv6 93 checks: 94 exact-len: 16 95 - 96 name: local-ipv4 97 type: u32 98 doc: The local IPv4 to be used to send packets to the peer (UDP only) 99 byte-order: big-endian 100 display-hint: ipv4 101 - 102 name: local-ipv6 103 type: binary 104 doc: The local IPv6 to be used to send packets to the peer (UDP only) 105 display-hint: ipv6 106 checks: 107 exact-len: 16 108 - 109 name: local-port 110 type: u16 111 doc: The local port to be used to send packets to the peer (UDP only) 112 byte-order: big-endian 113 checks: 114 min: 1 115 - 116 name: keepalive-interval 117 type: u32 118 doc: >- 119 The number of seconds after which a keep alive message is sent to the 120 peer 121 - 122 name: keepalive-timeout 123 type: u32 124 doc: >- 125 The number of seconds from the last activity after which the peer is 126 assumed dead 127 - 128 name: del-reason 129 type: u32 130 doc: The reason why a peer was deleted 131 enum: del-peer-reason 132 - 133 name: vpn-rx-bytes 134 type: uint 135 doc: Number of bytes received over the tunnel 136 - 137 name: vpn-tx-bytes 138 type: uint 139 doc: Number of bytes transmitted over the tunnel 140 - 141 name: vpn-rx-packets 142 type: uint 143 doc: Number of packets received over the tunnel 144 - 145 name: vpn-tx-packets 146 type: uint 147 doc: Number of packets transmitted over the tunnel 148 - 149 name: link-rx-bytes 150 type: uint 151 doc: Number of bytes received at the transport level 152 - 153 name: link-tx-bytes 154 type: uint 155 doc: Number of bytes transmitted at the transport level 156 - 157 name: link-rx-packets 158 type: uint 159 doc: Number of packets received at the transport level 160 - 161 name: link-tx-packets 162 type: uint 163 doc: Number of packets transmitted at the transport level 164 - 165 name: tx-id 166 type: u32 167 doc: >- 168 The ID value used when transmitting packets to this peer. This 169 way outgoing packets can have a different ID than incoming ones. 170 Useful in multipeer-to-multipeer connections, where each peer 171 will advertise the tx-id to be used on the link. 172 checks: 173 max: 0xFFFFFF 174 - 175 name: peer-new-input 176 subset-of: peer 177 attributes: 178 - 179 name: id 180 - 181 name: remote-ipv4 182 - 183 name: remote-ipv6 184 - 185 name: remote-ipv6-scope-id 186 - 187 name: remote-port 188 - 189 name: socket 190 - 191 name: vpn-ipv4 192 - 193 name: vpn-ipv6 194 - 195 name: local-ipv4 196 - 197 name: local-ipv6 198 - 199 name: keepalive-interval 200 - 201 name: keepalive-timeout 202 - 203 name: tx-id 204 - 205 name: peer-set-input 206 subset-of: peer 207 attributes: 208 - 209 name: id 210 - 211 name: remote-ipv4 212 - 213 name: remote-ipv6 214 - 215 name: remote-ipv6-scope-id 216 - 217 name: remote-port 218 - 219 name: vpn-ipv4 220 - 221 name: vpn-ipv6 222 - 223 name: local-ipv4 224 - 225 name: local-ipv6 226 - 227 name: keepalive-interval 228 - 229 name: keepalive-timeout 230 - 231 name: tx-id 232 - 233 name: peer-del-input 234 subset-of: peer 235 attributes: 236 - 237 name: id 238 - 239 name: keyconf 240 attributes: 241 - 242 name: peer-id 243 type: u32 244 doc: >- 245 The unique ID of the peer in the device context. To be used to 246 identify peers during key operations 247 checks: 248 max: 0xFFFFFF 249 - 250 name: slot 251 type: u32 252 doc: The slot where the key should be stored 253 enum: key-slot 254 - 255 name: key-id 256 doc: >- 257 The unique ID of the key in the peer context. Used to fetch the 258 correct key upon decryption 259 type: u32 260 checks: 261 max: 7 262 - 263 name: cipher-alg 264 type: u32 265 doc: The cipher to be used when communicating with the peer 266 enum: cipher-alg 267 - 268 name: encrypt-dir 269 type: nest 270 doc: Key material for encrypt direction 271 nested-attributes: keydir 272 - 273 name: decrypt-dir 274 type: nest 275 doc: Key material for decrypt direction 276 nested-attributes: keydir 277 - 278 name: keydir 279 attributes: 280 - 281 name: cipher-key 282 type: binary 283 doc: The actual key to be used by the cipher 284 checks: 285 max-len: 256 286 - 287 name: nonce-tail 288 type: binary 289 doc: >- 290 Random nonce to be concatenated to the packet ID, in order to 291 obtain the actual cipher IV 292 checks: 293 exact-len: nonce-tail-size 294 295 - 296 name: keyconf-get 297 subset-of: keyconf 298 attributes: 299 - 300 name: peer-id 301 - 302 name: slot 303 - 304 name: key-id 305 - 306 name: cipher-alg 307 - 308 name: keyconf-swap-input 309 subset-of: keyconf 310 attributes: 311 - 312 name: peer-id 313 - 314 name: keyconf-del-input 315 subset-of: keyconf 316 attributes: 317 - 318 name: peer-id 319 - 320 name: slot 321 - 322 name: ovpn 323 attributes: 324 - 325 name: ifindex 326 type: u32 327 doc: Index of the ovpn interface to operate on 328 - 329 name: peer 330 type: nest 331 doc: >- 332 The peer object containing the attributed of interest for the specific 333 operation 334 nested-attributes: peer 335 - 336 name: keyconf 337 type: nest 338 doc: Peer specific cipher configuration 339 nested-attributes: keyconf 340 - 341 name: ovpn-peer-new-input 342 subset-of: ovpn 343 attributes: 344 - 345 name: ifindex 346 - 347 name: peer 348 nested-attributes: peer-new-input 349 - 350 name: ovpn-peer-set-input 351 subset-of: ovpn 352 attributes: 353 - 354 name: ifindex 355 - 356 name: peer 357 nested-attributes: peer-set-input 358 - 359 name: ovpn-peer-del-input 360 subset-of: ovpn 361 attributes: 362 - 363 name: ifindex 364 - 365 name: peer 366 nested-attributes: peer-del-input 367 - 368 name: ovpn-keyconf-get 369 subset-of: ovpn 370 attributes: 371 - 372 name: ifindex 373 - 374 name: keyconf 375 nested-attributes: keyconf-get 376 - 377 name: ovpn-keyconf-swap-input 378 subset-of: ovpn 379 attributes: 380 - 381 name: ifindex 382 - 383 name: keyconf 384 nested-attributes: keyconf-swap-input 385 - 386 name: ovpn-keyconf-del-input 387 subset-of: ovpn 388 attributes: 389 - 390 name: ifindex 391 - 392 name: keyconf 393 nested-attributes: keyconf-del-input 394 395operations: 396 list: 397 - 398 name: peer-new 399 attribute-set: ovpn-peer-new-input 400 flags: [admin-perm] 401 doc: Add a remote peer 402 do: 403 pre: ovpn-nl-pre-doit 404 post: ovpn-nl-post-doit 405 request: 406 attributes: 407 - ifindex 408 - peer 409 - 410 name: peer-set 411 attribute-set: ovpn-peer-set-input 412 flags: [admin-perm] 413 doc: modify a remote peer 414 do: 415 pre: ovpn-nl-pre-doit 416 post: ovpn-nl-post-doit 417 request: 418 attributes: 419 - ifindex 420 - peer 421 - 422 name: peer-get 423 attribute-set: ovpn 424 flags: [admin-perm] 425 doc: Retrieve data about existing remote peers (or a specific one) 426 do: 427 pre: ovpn-nl-pre-doit 428 post: ovpn-nl-post-doit 429 request: 430 attributes: 431 - ifindex 432 - peer 433 reply: 434 attributes: 435 - peer 436 dump: 437 request: 438 attributes: 439 - ifindex 440 reply: 441 attributes: 442 - peer 443 - 444 name: peer-del 445 attribute-set: ovpn-peer-del-input 446 flags: [admin-perm] 447 doc: Delete existing remote peer 448 do: 449 pre: ovpn-nl-pre-doit 450 post: ovpn-nl-post-doit 451 request: 452 attributes: 453 - ifindex 454 - peer 455 - 456 name: peer-del-ntf 457 doc: Notification about a peer being deleted 458 notify: peer-get 459 mcgrp: peers 460 461 - 462 name: key-new 463 attribute-set: ovpn 464 flags: [admin-perm] 465 doc: Add a cipher key for a specific peer 466 do: 467 pre: ovpn-nl-pre-doit 468 post: ovpn-nl-post-doit 469 request: 470 attributes: 471 - ifindex 472 - keyconf 473 - 474 name: key-get 475 attribute-set: ovpn-keyconf-get 476 flags: [admin-perm] 477 doc: Retrieve non-sensitive data about peer key and cipher 478 do: 479 pre: ovpn-nl-pre-doit 480 post: ovpn-nl-post-doit 481 request: 482 attributes: 483 - ifindex 484 - keyconf 485 reply: 486 attributes: 487 - keyconf 488 - 489 name: key-swap 490 attribute-set: ovpn-keyconf-swap-input 491 flags: [admin-perm] 492 doc: Swap primary and secondary session keys for a specific peer 493 do: 494 pre: ovpn-nl-pre-doit 495 post: ovpn-nl-post-doit 496 request: 497 attributes: 498 - ifindex 499 - keyconf 500 - 501 name: key-swap-ntf 502 notify: key-get 503 doc: >- 504 Notification about key having exhausted its IV space and requiring 505 renegotiation 506 mcgrp: peers 507 - 508 name: key-del 509 attribute-set: ovpn-keyconf-del-input 510 flags: [admin-perm] 511 doc: Delete cipher key for a specific peer 512 do: 513 pre: ovpn-nl-pre-doit 514 post: ovpn-nl-post-doit 515 request: 516 attributes: 517 - ifindex 518 - keyconf 519 520 - 521 name: peer-float-ntf 522 doc: Notification about a peer floating (changing its remote UDP endpoint) 523 notify: peer-get 524 mcgrp: peers 525 526mcast-groups: 527 list: 528 - 529 name: peers 530