Documentation/netlink/specs/psp.yaml

# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
---
name: psp

doc:
  PSP Security Protocol Generic Netlink family.

definitions:
  -
    type: enum
    name: version
    entries: [hdr0-aes-gcm-128, hdr0-aes-gcm-256,
              hdr0-aes-gmac-128, hdr0-aes-gmac-256]

attribute-sets:
  -
    name: dev
    attributes:
      -
        name: id
        doc: PSP device ID.
        type: u32
        checks:
          min: 1
      -
        name: ifindex
        doc: ifindex of the main netdevice linked to the PSP device.
        type: u32
      -
        name: psp-versions-cap
        doc: Bitmask of PSP versions supported by the device.
        type: u32
        enum: version
        enum-as-flags: true
      -
        name: psp-versions-ena
        doc: Bitmask of currently enabled (accepted on Rx) PSP versions.
        type: u32
        enum: version
        enum-as-flags: true
  -
    name: assoc
    attributes:
      -
        name: dev-id
        doc: PSP device ID.
        type: u32
        checks:
          min: 1
      -
        name: version
        doc: |
          PSP versions (AEAD and protocol version) used by this association,
          dictates the size of the key.
        type: u32
        enum: version
      -
        name: rx-key
        type: nest
        nested-attributes: keys
      -
        name: tx-key
        type: nest
        nested-attributes: keys
      -
        name: sock-fd
        doc: Sockets which should be bound to the association immediately.
        type: u32
  -
    name: keys
    attributes:
      -
        name: key
        type: binary
      -
        name: spi
        doc: Security Parameters Index (SPI) of the association.
        type: u32

operations:
  list:
    -
      name: dev-get
      doc: Get / dump information about PSP capable devices on the system.
      attribute-set: dev
      do:
        request:
          attributes:
            - id
        reply: &dev-all
          attributes:
            - id
            - ifindex
            - psp-versions-cap
            - psp-versions-ena
        pre: psp-device-get-locked
        post: psp-device-unlock
      dump:
        reply: *dev-all
    -
      name: dev-add-ntf
      doc: Notification about device appearing.
      notify: dev-get
      mcgrp: mgmt
    -
      name: dev-del-ntf
      doc: Notification about device disappearing.
      notify: dev-get
      mcgrp: mgmt
    -
      name: dev-set
      doc: Set the configuration of a PSP device.
      attribute-set: dev
      do:
        request:
          attributes:
            - id
            - psp-versions-ena
        reply:
          attributes: []
        pre: psp-device-get-locked
        post: psp-device-unlock
    -
      name: dev-change-ntf
      doc: Notification about device configuration being changed.
      notify: dev-get
      mcgrp: mgmt

    -
      name: key-rotate
      doc: Rotate the device key.
      attribute-set: dev
      do:
        request:
          attributes:
            - id
        reply:
          attributes:
            - id
        pre: psp-device-get-locked
        post: psp-device-unlock
    -
      name: key-rotate-ntf
      doc: Notification about device key getting rotated.
      notify: key-rotate
      mcgrp: use

    -
      name: rx-assoc
      doc: Allocate a new Rx key + SPI pair, associate it with a socket.
      attribute-set: assoc
      do:
        request:
          attributes:
            - dev-id
            - version
            - sock-fd
        reply:
          attributes:
            - dev-id
            - rx-key
        pre: psp-assoc-device-get-locked
        post: psp-device-unlock
    -
      name: tx-assoc
      doc: Add a PSP Tx association.
      attribute-set: assoc
      do:
        request:
          attributes:
            - dev-id
            - version
            - tx-key
            - sock-fd
        reply:
          attributes: []
        pre: psp-assoc-device-get-locked
        post: psp-device-unlock

mcast-groups:
  list:
    -
      name: mgmt
    -
      name: use

...