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