xref: /linux/Documentation/netlink/specs/handshake.yaml (revision 47dbcfdf942a35dbf842ea05bb2248fcda411da7) 
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: const
17    name: max-errno
18    value: 4095
19    header: linux/err.h
20    scope: kernel
21  -
22    type: enum
23    name: handler-class
24    value-start: 0
25    entries: [none, tlshd]
26    render-max: true
27  -
28    type: enum
29    name: msg-type
30    value-start: 0
31    entries: [unspec, clienthello, serverhello]
32  -
33    type: enum
34    name: auth
35    value-start: 0
36    entries: [unspec, unauth, psk, x509]
37
38attribute-sets:
39  -
40    name: x509
41    attributes:
42      -
43        name: cert
44        type: s32
45      -
46        name: privkey
47        type: s32
48  -
49    name: accept
50    attributes:
51      -
52        name: sockfd
53        type: s32
54      -
55        name: handler-class
56        type: u32
57        enum: handler-class
58      -
59        name: message-type
60        type: u32
61        enum: msg-type
62      -
63        name: timeout
64        type: u32
65      -
66        name: auth-mode
67        type: u32
68        enum: auth
69      -
70        name: peer-identity
71        type: s32
72        multi-attr: true
73      -
74        name: certificate
75        type: nest
76        nested-attributes: x509
77        multi-attr: true
78      -
79        name: peername
80        type: string
81      -
82        name: keyring
83        type: s32
84  -
85    name: done
86    attributes:
87      -
88        name: status
89        type: u32
90        checks:
91          max: max-errno
92      -
93        name: sockfd
94        type: s32
95      -
96        name: remote-auth
97        type: s32
98        multi-attr: true
99
100operations:
101  list:
102    -
103      name: ready
104      doc: Notify handlers that a new handshake request is waiting
105      notify: accept
106    -
107      name: accept
108      doc: Handler retrieves next queued handshake request
109      attribute-set: accept
110      flags: [admin-perm]
111      do:
112        request:
113          attributes:
114            - handler-class
115        reply:
116          attributes:
117            - sockfd
118            - message-type
119            - timeout
120            - auth-mode
121            - peer-identity
122            - certificate
123            - peername
124            - keyring
125    -
126      name: done
127      doc: Handler reports handshake completion
128      attribute-set: done
129      flags: [admin-perm]
130      do:
131        request:
132          attributes:
133            - status
134            - sockfd
135            - remote-auth
136
137mcast-groups:
138  list:
139    -
140      name: none
141    -
142      name: tlshd
143