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
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
82 Typically the encryption or decryption is performed in software,
83 but it may also be performed by co-processors.
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 The current TLS transmit mode of a socket can be queried via the
137 A socket using TLS transmit offload can also set the
139 socket option to toggle between
142 .Dv TCP_TLS_MODE_IFNET .
144 Once TLS receive is enabled by a successful set of the
147 all data read from the socket is returned as decrypted TLS records.
148 Each received TLS record must be read from the socket using
150 Each received TLS record will contain a
152 control message along with the decrypted payload.
153 The control message contains a
154 .Vt struct tls_get_record
155 which includes fields from the TLS record header.
156 If an invalid or corrupted TLS record is received,
158 will fail with one of the following errors:
161 The version fields in a TLS record's header did not match the version required
163 .Vt struct tls_enable
164 structure used to enable in-kernel TLS.
166 A TLS record's length was either too small or too large.
168 The connection was closed after sending a truncated TLS record.
170 The TLS record failed to match the included authentication tag.
173 The current TLS receive mode of a socket can be queried via the
177 the mode cannot be changed.
180 uses several sysctl nodes under the
183 A few of them are described below:
184 .Bl -tag -width ".Va kern.ipc.tls.cbc_enable"
185 .It Va kern.ipc.tls.enable
186 Determines if new kernel TLS sessions can be created.
187 .It Va kern.ipc.tls.cbc_enable
188 Determines if new kernel TLS sessions with a cipher suite using AES-CBC
190 .It Va kern.ipc.tls.sw
191 A tree of nodes containing statistics for TLS sessions using
192 .Dv TCP_TLS_MODE_SW .
193 .It Va kern.ipc.tls.ifnet
194 A tree of nodes containing statistics for TLS sessions using
195 .Dv TCP_TLS_MODE_IFNET .
196 .It Va kern.ipc.tls.toe
197 A tree of nodes containing statistics for TLS sessions using
198 .Dv TCP_TLS_MODE_TOE .
199 .It Va kern.ipc.tls.stats
200 A tree of nodes containing various kernel TLS statistics.
204 .Va kern.ipc.mb_use_ext_pgs
205 sysctl controls whether the kernel may use unmapped mbufs.
206 They are required for TLS transmit.
207 .Ss Supported Hardware
212 drivers include support for the
213 .Dv TCP_TLS_MODE_IFNET
218 driver includes support for the
221 .Ss Supported Libraries
222 OpenSSL 3.0 and later include support for
225 .Fa security/openssl-devel
226 port may also be built with support for
231 OpenSSL in the base system includes KTLS support when built with
232 .Dv WITH_OPENSSL_KTLS .
234 Applications using a supported library should generally work with
236 without any changes provided they use standard interfaces such as
240 Additional performance may be gained by the use of
242 .Sh IMPLEMENTATION NOTES
244 assumes the presence of a direct map of physical memory when performing
245 software encryption and decryption.
246 As a result, it is only supported on architectures with a direct map.
256 Kernel TLS first appeared in