handshake.yaml

  1# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
  2#
  3# Author: Chuck Lever <chuck.lever@oracle.com>
  4#
  5# Copyright (c) 2023, Oracle and/or its affiliates.
  6#
  7---
  8name: handshake
  9
 10protocol: genetlink
 11
 12doc: Netlink protocol to request a transport layer security handshake.
 13
 14definitions:
 15  -
 16    type: enum
 17    name: handler-class
 18    value-start: 0
 19    entries: [none, tlshd, max]
 20  -
 21    type: enum
 22    name: msg-type
 23    value-start: 0
 24    entries: [unspec, clienthello, serverhello]
 25  -
 26    type: enum
 27    name: auth
 28    value-start: 0
 29    entries: [unspec, unauth, psk, x509]
 30
 31attribute-sets:
 32  -
 33    name: x509
 34    attributes:
 35      -
 36        name: cert
 37        type: s32
 38      -
 39        name: privkey
 40        type: s32
 41  -
 42    name: accept
 43    attributes:
 44      -
 45        name: sockfd
 46        type: s32
 47      -
 48        name: handler-class
 49        type: u32
 50        enum: handler-class
 51      -
 52        name: message-type
 53        type: u32
 54        enum: msg-type
 55      -
 56        name: timeout
 57        type: u32
 58      -
 59        name: auth-mode
 60        type: u32
 61        enum: auth
 62      -
 63        name: peer-identity
 64        type: u32
 65        multi-attr: true
 66      -
 67        name: certificate
 68        type: nest
 69        nested-attributes: x509
 70        multi-attr: true
 71      -
 72        name: peername
 73        type: string
 74      -
 75        name: keyring
 76        type: u32
 77  -
 78    name: done
 79    attributes:
 80      -
 81        name: status
 82        type: u32
 83      -
 84        name: sockfd
 85        type: s32
 86      -
 87        name: remote-auth
 88        type: u32
 89        multi-attr: true
 90
 91operations:
 92  list:
 93    -
 94      name: ready
 95      doc: Notify handlers that a new handshake request is waiting
 96      notify: accept
 97    -
 98      name: accept
 99      doc: Handler retrieves next queued handshake request
100      attribute-set: accept
101      flags: [admin-perm]
102      do:
103        request:
104          attributes:
105            - handler-class
106        reply:
107          attributes:
108            - sockfd
109            - message-type
110            - timeout
111            - auth-mode
112            - peer-identity
113            - certificate
114            - peername
115            - keyring
116    -
117      name: done
118      doc: Handler reports handshake completion
119      attribute-set: done
120      do:
121        request:
122          attributes:
123            - status
124            - sockfd
125            - remote-auth
126
127mcast-groups:
128  list:
129    -
130      name: none
131    -
132      name: tlshd