Lines Matching +full:use +full:- +full:handshake
1 .. SPDX-License-Identifier: GPL-2.0
4 In-Kernel TLS Handshake
11 over TCP. TLS provides end-to-end data integrity and confidentiality in
15 does not handle the TLS handshake subprotocol which is used to establish
16 a TLS session. Kernel consumers can use the API described here to
19 There are several possible ways to provide a handshake service in the
21 implementations so that in-kernel TLS consumers do not need to be
22 aware of how the handshake gets done.
25 User handshake agent
28 As of this writing, there is no TLS handshake implementation in the
29 Linux kernel. To provide a handshake service, a handshake agent
31 kernel consumer might require a TLS handshake. Handshake agents listen
32 for events sent from the kernel that indicate a handshake request is
35 An open socket is passed to a handshake agent via a netlink operation,
37 If the handshake completes successfully, the handshake agent promotes
38 the socket to use the TLS ULP and sets the session information using the
39 SOL_TLS socket options. The handshake agent returns the socket to the
43 Kernel Handshake API
46 A kernel TLS consumer initiates a client-side TLS handshake on an open
50 .. code-block:: c
67 while the handshake is in progress. The consumer must also have
68 instantiated a struct file in sock->file.
71 @ta_done contains a callback function that is invoked when the handshake
72 has completed. Further explanation of this function is in the "Handshake
75 The consumer can provide a NUL-terminated hostname in the @ta_peername
80 handshake agent to exit after a number of milliseconds. This enables the
81 socket to be fully closed once both the kernel and the handshake agent
85 keys, and pre-shared keys are provided to the handshake agent in keys
86 that are instantiated by the consumer before making the handshake
88 the handshake agent's process keyring in the @ta_keyring field to prevent
91 To request an x.509-authenticated TLS session, the consumer fills in
96 .. code-block:: c
100 The function returns zero when the handshake request is under way. A
102 for this socket. The function returns a negative errno if the handshake
107 To initiate a client-side TLS handshake with a pre-shared key, use:
109 .. code-block:: c
119 To initiate an anonymous client-side TLS handshake use:
121 .. code-block:: c
125 The handshake agent presents no peer identity information to the remote
126 during this type of handshake. Only server authentication (ie the client
127 verifies the server's identity) is performed during the handshake. Thus
131 Consumers that are in-kernel servers use:
133 .. code-block:: c
139 .. code-block:: c
146 If the consumer needs to cancel the handshake request, say, due to a ^C
149 .. code-block:: c
153 This function returns true if the handshake request associated with
154 @sock has been canceled. The consumer's handshake completion callback
159 Handshake Completion
162 When the handshake agent has completed processing, it notifies the
164 the consumer's handshake completion callback, provided in the @ta_done
169 .. code-block:: c
177 thread waiting for the handshake to complete.
179 The success status of the handshake is returned via the @status
182 +------------+----------------------------------------------+
186 +------------+----------------------------------------------+
187 | -EACCESS | Remote peer rejected the handshake or |
189 +------------+----------------------------------------------+
190 | -ENOMEM | Temporary resource allocation failure |
191 +------------+----------------------------------------------+
192 | -EINVAL | Consumer provided an invalid argument |
193 +------------+----------------------------------------------+
194 | -ENOKEY | Missing authentication material |
195 +------------+----------------------------------------------+
196 | -EIO | An unexpected fault occurred |
197 +------------+----------------------------------------------+
204 handshake failed.
208 --------------------
210 While a handshake is under way, the kernel consumer must alter the
212 Once the handshake completion callback function has been invoked, normal
221 (decrypted) application data, alerts, and handshake packets once the
222 socket has been promoted to use the TLS ULP.