xref: /linux/Documentation/netlink/specs/handshake.yaml (revision 8be4d31cb8aaeea27bde4b7ddb26e28a89062ebf) 
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
133