path: root/Documentation/netlink/specs/ovpn.yaml

# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
#
# Author: Antonio Quartulli <antonio@openvpn.net>
#
# Copyright (c) 2024-2025, OpenVPN Inc.
#
---
name: ovpn

protocol: genetlink

doc: Netlink protocol to control OpenVPN network devices

definitions:
  -
    type: const
    name: nonce-tail-size
    value: 8
  -
    type: enum
    name: cipher-alg
    entries: [none, aes-gcm, chacha20-poly1305]
  -
    type: enum
    name: del-peer-reason
    entries:
      - teardown
      - userspace
      - expired
      - transport-error
      - transport-disconnect
  -
    type: enum
    name: key-slot
    entries: [primary, secondary]

attribute-sets:
  -
    name: peer
    attributes:
      -
        name: id
        type: u32
        doc: >-
          The unique ID of the peer in the device context. To be used to
          identify peers during operations for a specific device
        checks:
          max: 0xFFFFFF
      -
        name: remote-ipv4
        type: u32
        doc: The remote IPv4 address of the peer
        byte-order: big-endian
        display-hint: ipv4
      -
        name: remote-ipv6
        type: binary
        doc: The remote IPv6 address of the peer
        display-hint: ipv6
        checks:
          exact-len: 16
      -
        name: remote-ipv6-scope-id
        type: u32
        doc: The scope id of the remote IPv6 address of the peer (RFC2553)
      -
        name: remote-port
        type: u16
        doc: The remote port of the peer
        byte-order: big-endian
        checks:
          min: 1
      -
        name: socket
        type: u32
        doc: The socket to be used to communicate with the peer
      -
        name: socket-netnsid
        type: s32
        doc: The ID of the netns the socket assigned to this peer lives in
      -
        name: vpn-ipv4
        type: u32
        doc: The IPv4 address assigned to the peer by the server
        byte-order: big-endian
        display-hint: ipv4
      -
        name: vpn-ipv6
        type: binary
        doc: The IPv6 address assigned to the peer by the server
        display-hint: ipv6
        checks:
          exact-len: 16
      -
        name: local-ipv4
        type: u32
        doc: The local IPv4 to be used to send packets to the peer (UDP only)
        byte-order: big-endian
        display-hint: ipv4
      -
        name: local-ipv6
        type: binary
        doc: The local IPv6 to be used to send packets to the peer (UDP only)
        display-hint: ipv6
        checks:
          exact-len: 16
      -
        name: local-port
        type: u16
        doc: The local port to be used to send packets to the peer (UDP only)
        byte-order: big-endian
        checks:
          min: 1
      -
        name: keepalive-interval
        type: u32
        doc: >-
          The number of seconds after which a keep alive message is sent to the
          peer
      -
        name: keepalive-timeout
        type: u32
        doc: >-
          The number of seconds from the last activity after which the peer is
          assumed dead
      -
        name: del-reason
        type: u32
        doc: The reason why a peer was deleted
        enum: del-peer-reason
      -
        name: vpn-rx-bytes
        type: uint
        doc: Number of bytes received over the tunnel
      -
        name: vpn-tx-bytes
        type: uint
        doc: Number of bytes transmitted over the tunnel
      -
        name: vpn-rx-packets
        type: uint
        doc: Number of packets received over the tunnel
      -
        name: vpn-tx-packets
        type: uint
        doc: Number of packets transmitted over the tunnel
      -
        name: link-rx-bytes
        type: uint
        doc: Number of bytes received at the transport level
      -
        name: link-tx-bytes
        type: uint
        doc: Number of bytes transmitted at the transport level
      -
        name: link-rx-packets
        type: uint
        doc: Number of packets received at the transport level
      -
        name: link-tx-packets
        type: uint
        doc: Number of packets transmitted at the transport level
  -
    name: peer-new-input
    subset-of: peer
    attributes:
      -
        name: id
      -
        name: remote-ipv4
      -
        name: remote-ipv6
      -
        name: remote-ipv6-scope-id
      -
        name: remote-port
      -
        name: socket
      -
        name: vpn-ipv4
      -
        name: vpn-ipv6
      -
        name: local-ipv4
      -
        name: local-ipv6
      -
        name: keepalive-interval
      -
        name: keepalive-timeout
  -
    name: peer-set-input
    subset-of: peer
    attributes:
      -
        name: id
      -
        name: remote-ipv4
      -
        name: remote-ipv6
      -
        name: remote-ipv6-scope-id
      -
        name: remote-port
      -
        name: vpn-ipv4
      -
        name: vpn-ipv6
      -
        name: local-ipv4
      -
        name: local-ipv6
      -
        name: keepalive-interval
      -
        name: keepalive-timeout
  -
    name: peer-del-input
    subset-of: peer
    attributes:
      -
        name: id
  -
    name: keyconf
    attributes:
      -
        name: peer-id
        type: u32
        doc: >-
          The unique ID of the peer in the device context. To be used to
          identify peers during key operations
        checks:
          max: 0xFFFFFF
      -
        name: slot
        type: u32
        doc: The slot where the key should be stored
        enum: key-slot
      -
        name: key-id
        doc: >-
          The unique ID of the key in the peer context. Used to fetch the
          correct key upon decryption
        type: u32
        checks:
          max: 7
      -
        name: cipher-alg
        type: u32
        doc: The cipher to be used when communicating with the peer
        enum: cipher-alg
      -
        name: encrypt-dir
        type: nest
        doc: Key material for encrypt direction
        nested-attributes: keydir
      -
        name: decrypt-dir
        type: nest
        doc: Key material for decrypt direction
        nested-attributes: keydir
  -
    name: keydir
    attributes:
      -
        name: cipher-key
        type: binary
        doc: The actual key to be used by the cipher
        checks:
          max-len: 256
      -
        name: nonce-tail
        type: binary
        doc: >-
          Random nonce to be concatenated to the packet ID, in order to
          obtain the actual cipher IV
        checks:
          exact-len: nonce-tail-size

  -
    name: keyconf-get
    subset-of: keyconf
    attributes:
      -
        name: peer-id
      -
        name: slot
      -
        name: key-id
      -
        name: cipher-alg
  -
    name: keyconf-swap-input
    subset-of: keyconf
    attributes:
      -
        name: peer-id
  -
    name: keyconf-del-input
    subset-of: keyconf
    attributes:
      -
        name: peer-id
      -
        name: slot
  -
    name: ovpn
    attributes:
      -
        name: ifindex
        type: u32
        doc: Index of the ovpn interface to operate on
      -
        name: peer
        type: nest
        doc: >-
          The peer object containing the attributed of interest for the specific
          operation
        nested-attributes: peer
      -
        name: keyconf
        type: nest
        doc: Peer specific cipher configuration
        nested-attributes: keyconf
  -
    name: ovpn-peer-new-input
    subset-of: ovpn
    attributes:
      -
        name: ifindex
      -
        name: peer
        nested-attributes: peer-new-input
  -
    name: ovpn-peer-set-input
    subset-of: ovpn
    attributes:
      -
        name: ifindex
      -
        name: peer
        nested-attributes: peer-set-input
  -
    name: ovpn-peer-del-input
    subset-of: ovpn
    attributes:
      -
        name: ifindex
      -
        name: peer
        nested-attributes: peer-del-input
  -
    name: ovpn-keyconf-get
    subset-of: ovpn
    attributes:
      -
        name: ifindex
      -
        name: keyconf
        nested-attributes: keyconf-get
  -
    name: ovpn-keyconf-swap-input
    subset-of: ovpn
    attributes:
      -
        name: ifindex
      -
        name: keyconf
        nested-attributes: keyconf-swap-input
  -
    name: ovpn-keyconf-del-input
    subset-of: ovpn
    attributes:
      -
        name: ifindex
      -
        name: keyconf
        nested-attributes: keyconf-del-input

operations:
  list:
    -
      name: peer-new
      attribute-set: ovpn-peer-new-input
      flags: [admin-perm]
      doc: Add a remote peer
      do:
        pre: ovpn-nl-pre-doit
        post: ovpn-nl-post-doit
        request:
          attributes:
            - ifindex
            - peer
    -
      name: peer-set
      attribute-set: ovpn-peer-set-input
      flags: [admin-perm]
      doc: modify a remote peer
      do:
        pre: ovpn-nl-pre-doit
        post: ovpn-nl-post-doit
        request:
          attributes:
            - ifindex
            - peer
    -
      name: peer-get
      attribute-set: ovpn
      flags: [admin-perm]
      doc: Retrieve data about existing remote peers (or a specific one)
      do:
        pre: ovpn-nl-pre-doit
        post: ovpn-nl-post-doit
        request:
          attributes:
            - ifindex
            - peer
        reply:
          attributes:
            - peer
      dump:
        request:
          attributes:
            - ifindex
        reply:
          attributes:
            - peer
    -
      name: peer-del
      attribute-set: ovpn-peer-del-input
      flags: [admin-perm]
      doc: Delete existing remote peer
      do:
        pre: ovpn-nl-pre-doit
        post: ovpn-nl-post-doit
        request:
          attributes:
            - ifindex
            - peer
    -
      name: peer-del-ntf
      doc: Notification about a peer being deleted
      notify: peer-get
      mcgrp: peers

    -
      name: key-new
      attribute-set: ovpn
      flags: [admin-perm]
      doc: Add a cipher key for a specific peer
      do:
        pre: ovpn-nl-pre-doit
        post: ovpn-nl-post-doit
        request:
          attributes:
            - ifindex
            - keyconf
    -
      name: key-get
      attribute-set: ovpn-keyconf-get
      flags: [admin-perm]
      doc: Retrieve non-sensitive data about peer key and cipher
      do:
        pre: ovpn-nl-pre-doit
        post: ovpn-nl-post-doit
        request:
          attributes:
            - ifindex
            - keyconf
        reply:
          attributes:
            - keyconf
    -
      name: key-swap
      attribute-set: ovpn-keyconf-swap-input
      flags: [admin-perm]
      doc: Swap primary and secondary session keys for a specific peer
      do:
        pre: ovpn-nl-pre-doit
        post: ovpn-nl-post-doit
        request:
          attributes:
            - ifindex
            - keyconf
    -
      name: key-swap-ntf
      notify: key-get
      doc: >-
        Notification about key having exhausted its IV space and requiring
        renegotiation
      mcgrp: peers
    -
      name: key-del
      attribute-set: ovpn-keyconf-del-input
      flags: [admin-perm]
      doc: Delete cipher key for a specific peer
      do:
        pre: ovpn-nl-pre-doit
        post: ovpn-nl-post-doit
        request:
          attributes:
            - ifindex
            - keyconf

mcast-groups:
  list:
    -
      name: peers