Family psp netlink specification

Summary

PSP Security Protocol Generic Netlink family.

Operations

dev-get

Get / dump information about PSP capable devices on the system.

attribute-set:

dev

do:

request

attributes:

[id]

reply

attributes:

[id, ifindex, psp-versions-cap, psp-versions-ena, assoc-list, by-association]

pre

psp-device-get-locked

post

psp-device-unlock

dump:

reply

attributes:

[id, ifindex, psp-versions-cap, psp-versions-ena, assoc-list, by-association]

dev-add-ntf

Notification about device appearing.

notify:

dev-get

mcgrp:

mgmt

dev-del-ntf

Notification about device disappearing.

notify:

dev-get

mcgrp:

mgmt

dev-set

Set the configuration of a PSP device.

attribute-set:

dev

flags:

[admin-perm]

do:

request

attributes:

[id, psp-versions-ena]

reply

attributes:

[]

pre

psp-device-get-locked-admin

post

psp-device-unlock

dev-change-ntf

Notification about device configuration being changed.

notify:

dev-get

mcgrp:

mgmt

key-rotate

Rotate the device key.

attribute-set:

dev

flags:

[admin-perm]

do:

request

attributes:

[id]

reply

attributes:

[id]

pre

psp-device-get-locked-admin

post

psp-device-unlock

key-rotate-ntf

Notification about device key getting rotated.

notify:

key-rotate

mcgrp:

use

rx-assoc

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

tx-assoc

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

get-stats

Get device statistics.

attribute-set:

stats

do:

request

attributes:

[dev-id]

reply

attributes:

[dev-id, key-rotations, stale-events, rx-packets, rx-bytes, rx-auth-fail, rx-error, rx-bad, tx-packets, tx-bytes, tx-error]

pre

psp-device-get-locked

post

psp-device-unlock

dump:

reply

attributes:

[dev-id, key-rotations, stale-events, rx-packets, rx-bytes, rx-auth-fail, rx-error, rx-bad, tx-packets, tx-bytes, tx-error]

dev-assoc

Associate a network device with a PSP device.

attribute-set:

dev

flags:

[admin-perm]

do:

request

attributes:

[id, ifindex, nsid]

reply

attributes:

[]

pre

psp-device-get-locked-dev-assoc

post

psp-device-unlock

dev-disassoc

Disassociate a network device from a PSP device.

attribute-set:

dev

flags:

[admin-perm]

do:

request

attributes:

[id, ifindex, nsid]

reply

attributes:

[]

pre

psp-device-get-locked

post

psp-device-unlock

Multicast groups

• mgmt

• use

Definitions

version

type:

enum

entries:

• hdr0-aes-gcm-128

• hdr0-aes-gcm-256

• hdr0-aes-gmac-128

• hdr0-aes-gmac-256

Attribute sets

assoc-dev-info

ifindex (u32)

doc:

ifindex of an associated network device.

nsid (s32)

doc:

Network namespace ID of the associated device.

dev

id (u32)

doc:

PSP device ID.

ifindex (u32)

doc:

ifindex of the main netdevice linked to the PSP device, or the ifindex to associate with the PSP device.

psp-versions-cap (u32)

doc:

Bitmask of PSP versions supported by the device.

enum:

version

enum-as-flags:

True

psp-versions-ena (u32)

doc:

Bitmask of currently enabled (accepted on Rx) PSP versions.

enum:

version

enum-as-flags:

True

assoc-list (nest)

doc:

List of associated virtual devices.

nested-attributes:

assoc-dev-info

multi-attr:

True

nsid (s32)

doc:

Network namespace ID for the device to associate/disassociate. Optional for dev-assoc and dev-disassoc; if not present, the device is looked up in the caller’s network namespace.

by-association (flag)

doc:

Flag indicating the PSP device is an associated device from a different network namespace. Present when in associated namespace, absent when in primary/host namespace.

assoc

dev-id (u32)

doc:

PSP device ID.

version (u32)

doc:

PSP versions (AEAD and protocol version) used by this association, dictates the size of the key.

enum:

version

rx-key (nest)

nested-attributes:

keys

tx-key (nest)

nested-attributes:

keys

sock-fd (u32)

doc:

Sockets which should be bound to the association immediately.

keys

key (binary)

spi (u32)

doc:

Security Parameters Index (SPI) of the association.

stats

dev-id (u32)

doc:

PSP device ID.

key-rotations (uint)

doc:

Number of key rotations during the lifetime of the device. Kernel statistic.

stale-events (uint)

doc:

Number of times a socket’s Rx got shut down due to using a key which went stale (fully rotated out). Kernel statistic.

rx-packets (uint)

doc:

Number of successfully processed and authenticated PSP packets. Device statistic (from the PSP spec).

rx-bytes (uint)

doc:

Number of successfully authenticated PSP bytes received, counting from the first byte after the IV through the last byte of payload. The fixed initial portion of the PSP header (16 bytes) and the PSP trailer/ICV (16 bytes) are not included in this count. Device statistic (from the PSP spec).

rx-auth-fail (uint)

doc:

Number of received PSP packets with unsuccessful authentication. Device statistic (from the PSP spec).

rx-error (uint)

doc:

Number of received PSP packets with length/framing errors. Device statistic (from the PSP spec).

rx-bad (uint)

doc:

Number of received PSP packets with miscellaneous errors (invalid master key indicated by SPI, unsupported version, etc.) Device statistic (from the PSP spec).

tx-packets (uint)

doc:

Number of successfully processed PSP packets for transmission. Device statistic (from the PSP spec).

tx-bytes (uint)

doc:

Number of successfully processed PSP bytes for transmit, counting from the first byte after the IV through the last byte of payload. The fixed initial portion of the PSP header (16 bytes) and the PSP trailer/ICV (16 bytes) are not included in this count. Device statistic (from the PSP spec).

tx-error (uint)

doc:

Number of PSP packets for transmission with errors. Device statistic (from the PSP spec).