xref: /linux/Documentation/netlink/specs/handshake.yaml (revision 4b660dbd9ee2059850fd30e0df420ca7a38a1856) 
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: done
76    attributes:
77      -
78        name: status
79        type: u32
80      -
81        name: sockfd
82        type: s32
83      -
84        name: remote-auth
85        type: u32
86        multi-attr: true
87
88operations:
89  list:
90    -
91      name: ready
92      doc: Notify handlers that a new handshake request is waiting
93      notify: accept
94    -
95      name: accept
96      doc: Handler retrieves next queued handshake request
97      attribute-set: accept
98      flags: [ admin-perm ]
99      do:
100        request:
101          attributes:
102            - handler-class
103        reply:
104          attributes:
105            - sockfd
106            - message-type
107            - timeout
108            - auth-mode
109            - peer-identity
110            - certificate
111            - peername
112    -
113      name: done
114      doc: Handler reports handshake completion
115      attribute-set: done
116      do:
117        request:
118          attributes:
119            - status
120            - sockfd
121            - remote-auth
122
123mcast-groups:
124  list:
125    -
126      name: none
127    -
128      name: tlshd
129