1 .\" Copyright (c) 2020, Chelsio Inc
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions are met:
7 .\" 1. Redistributions of source code must retain the above copyright notice,
8 .\" this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the Chelsio Inc nor the names of its
15 .\" contributors may be used to endorse or promote products derived from
16 .\" this software without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
30 .\" * Other names and brands may be claimed as the property of others.
39 .Nd kernel Transport Layer Security
45 facility allows the kernel to perform Transport Layer Security (TLS)
46 framing on TCP sockets.
49 the initial handshake for a socket using TLS is performed in userland.
50 Once the session keys are negotiated,
51 they are provided to the kernel via the
56 Both socket options accept a
57 .Vt struct tls_so_enable
58 structure as their argument.
59 The members of this structure describe the cipher suite used for the
60 TLS session and provide the session keys used for the respective
64 only permits the session keys to be set once in each direction.
66 applications must disable rekeying when using
70 can operate in different modes.
71 A given socket may use different modes for transmit and receive,
72 or a socket may only offload a single direction.
73 The available modes are:
74 .Bl -tag -width "Dv TCP_TLS_MODE_IFNET"
75 .It Dv TCP_TLS_MODE_NONE
78 .It Dv TCP_TLS_MODE_SW
79 TLS records are encrypted or decrypted in the kernel in the socket
81 Typically the encryption or decryption is performed in software,
82 but it may also be performed by co-processors via
84 .It Dv TCP_TLS_MODE_IFNET
85 TLS records are encrypted or decrypted by the network interface card (NIC).
86 In this mode, the network stack does not work with encrypted data.
87 Instead, the NIC encrypts TLS records as they are being transmitted,
88 or decrypts received TLS records before providing them to the host.
90 Network interfaces which support this feature will advertise the
96 capabilities as reported by
98 These capabilities can also be controlled by
101 If a network interface supports rate limiting
102 (also known as packet pacing) for TLS offload,
103 the interface will advertise the
106 .It Dv TCP_TLS_MODE_TOE
107 TLS records are encrypted by the NIC using a TCP offload engine (TOE).
109 .Dv TCP_TLS_MODE_IFNET
110 in that the network stack does not work with encrypted data.
111 However, this mode works in tandem with a TOE to handle interactions
115 Once TLS transmit is enabled by a successful set of the
118 all data written on the socket is stored in TLS records and encrypted.
119 Most data is transmitted in application layer TLS records,
120 and the kernel chooses how to partition data among TLS records.
121 Individual TLS records with a fixed length and record type can be sent
124 with the TLS record type set in a
125 .Dv TLS_SET_RECORD_TYPE
127 The payload of this control message is a single byte holding the desired
129 This can be used to send TLS records with a type other than
130 application data (for example, handshake messages) or to send
131 application data records with specific contents (for example, empty
134 TLS transmit requires the use of unmapped mbufs.
135 Unmapped mbufs are not enabled by default, but can be enabled by
137 .Va kern.ipc.mb_use_ext_pgs
140 The current TLS transmit mode of a socket can be queried via the
143 A socket using TLS transmit offload can also set the
145 socket option to toggle between
148 .Dv TCP_TLS_MODE_IFNET .
150 Once TLS receive is enabled by a successful set of the
153 all data read from the socket is returned as decrypted TLS records.
154 Each received TLS record must be read from the socket using
156 Each received TLS record will contain a
158 control message along with the decrypted payload.
159 The control message contains a
160 .Vt struct tls_get_record
161 which includes fields from the TLS record header.
162 If an invalid or corrupted TLS record is received,
164 will fail with one of the following errors:
167 The version fields in a TLS record's header did not match the version required
169 .Vt struct tls_so_enable
170 structure used to enable in-kernel TLS.
172 A TLS record's length was either too small or too large.
174 The connection was closed after sending a truncated TLS record.
176 The TLS record failed to match the included authentication tag.
179 The current TLS receive mode of a socket can be queried via the
183 the mode cannot be changed.
186 uses several sysctl nodes under the
189 A few of them are described below:
190 .Bl -tag -width ".Va kern.ipc.tls.cbc_enable"
191 .It Va kern.ipc.tls.enable
192 Determines if new kernel TLS sessions can be created.
193 .It Va kern.ipc.tls.cbc_enable
194 Determines if new kernel TLS sessions with a cipher suite using AES-CBC
196 .It Va kern.ipc.tls.sw
197 A tree of nodes containing statistics for TLS sessions using
198 .Dv TCP_TLS_MODE_SW .
199 .It Va kern.ipc.tls.ifnet
200 A tree of nodes containing statistics for TLS sessions using
201 .Dv TCP_TLS_MODE_IFNET .
202 .It Va kern.ipc.tls.toe
203 A tree of nodes containing statistics for TLS sessions using
204 .Dv TCP_TLS_MODE_TOE .
205 .It Va kern.ipc.tls.stats
206 A tree of nodes containing various kernel TLS statistics.
209 The base system includes a software backend for the
213 to encrypt and decrypt TLS records.
214 This backend can be enabled by loading the
222 drivers include support for the
223 .Dv TCP_TLS_MODE_IFNET
228 driver includes support for the
231 .Ss Supported Libraries
232 OpenSSL 3.0 and later include support for
236 port may also be built with support for
242 Applications using a supported library should generally work with
244 without any changes provided they use standard interfaces such as
248 Additional performance may be gained by the use of
250 .Sh IMPLEMENTATION NOTES
252 assumes the presence of a direct map of physical memory when performing
253 software encryption and decryption.
254 As a result, it is only supported on architectures with a direct map.
263 Kernel TLS first appeared in