1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
<table class="head">
<tr>
<td class="head-ltitle">KTLS(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">KTLS(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">ktls</code> — <span class="Nd">kernel
Transport Layer Security</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">options KERN_TLS</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">ktls</code> facility allows the kernel to
perform Transport Layer Security (TLS) framing on TCP sockets. With
<code class="Nm">ktls</code>, the initial handshake for a socket using TLS
is performed in userland. Once the session keys are negotiated, they are
provided to the kernel via the <code class="Dv">TCP_TXTLS_ENABLE</code> and
<code class="Dv">TCP_RXTLS_ENABLE</code> socket options. Both socket options
accept a <var class="Vt">struct tls_enable</var> structure as their
argument. The members of this structure describe the cipher suite used for
the TLS session and provide the session keys used for the respective
direction.</p>
<p class="Pp"><code class="Nm">ktls</code> only permits the session keys to be
set once in each direction. As a result, applications must disable rekeying
when using <code class="Nm">ktls</code>.</p>
<section class="Ss">
<h2 class="Ss" id="Modes"><a class="permalink" href="#Modes">Modes</a></h2>
<p class="Pp"><code class="Nm">ktls</code> can operate in different modes. A
given socket may use different modes for transmit and receive, or a socket
may only offload a single direction. The available modes are:</p>
<dl class="Bl-tag">
<dt id="TCP_TLS_MODE_NONE"><a class="permalink" href="#TCP_TLS_MODE_NONE"><code class="Dv">TCP_TLS_MODE_NONE</code></a></dt>
<dd><code class="Nm">ktls</code> is not enabled.</dd>
<dt id="TCP_TLS_MODE_SW"><a class="permalink" href="#TCP_TLS_MODE_SW"><code class="Dv">TCP_TLS_MODE_SW</code></a></dt>
<dd>TLS records are encrypted or decrypted in the kernel in the socket layer
via <a class="Xr">crypto(9)</a>. Typically the encryption or decryption is
performed in software, but it may also be performed by co-processors.</dd>
<dt id="TCP_TLS_MODE_IFNET"><a class="permalink" href="#TCP_TLS_MODE_IFNET"><code class="Dv">TCP_TLS_MODE_IFNET</code></a></dt>
<dd>TLS records are encrypted or decrypted by the network interface card
(NIC). In this mode, the network stack does not work with encrypted data.
Instead, the NIC encrypts TLS records as they are being transmitted, or
decrypts received TLS records before providing them to the host.
<p class="Pp">Network interfaces which support this feature will advertise
the <code class="Dv">TXTLS4</code> (for IPv4) and/or
<code class="Dv">TXTLS6</code> (for IPv6) capabilities as reported by
<a class="Xr">ifconfig(8)</a>. These capabilities can also be controlled
by <a class="Xr">ifconfig(8)</a>.</p>
<p class="Pp">If a network interface supports rate limiting (also known as
packet pacing) for TLS offload, the interface will advertise the
<code class="Dv">TXTLS_RTLMT</code> capability.</p>
</dd>
<dt id="TCP_TLS_MODE_TOE"><a class="permalink" href="#TCP_TLS_MODE_TOE"><code class="Dv">TCP_TLS_MODE_TOE</code></a></dt>
<dd>TLS records are encrypted by the NIC using a TCP offload engine (TOE).
This is similar to <code class="Dv">TCP_TLS_MODE_IFNET</code> in that the
network stack does not work with encrypted data. However, this mode works
in tandem with a TOE to handle interactions between TCP and TLS.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Transmit"><a class="permalink" href="#Transmit">Transmit</a></h2>
<p class="Pp">Once TLS transmit is enabled by a successful set of the
<code class="Dv">TCP_TXTLS_ENABLE</code> socket option, all data written on
the socket is stored in TLS records and encrypted. Most data is transmitted
in application layer TLS records, and the kernel chooses how to partition
data among TLS records. Individual TLS records with a fixed length and
record type can be sent by <a class="Xr">sendmsg(2)</a> with the TLS record
type set in a <code class="Dv">TLS_SET_RECORD_TYPE</code> control message.
The payload of this control message is a single byte holding the desired TLS
record type. This can be used to send TLS records with a type other than
application data (for example, handshake messages) or to send application
data records with specific contents (for example, empty fragments).</p>
<p class="Pp">The current TLS transmit mode of a socket can be queried via the
<code class="Dv">TCP_TXTLS_MODE</code> socket option. A socket using TLS
transmit offload can also set the <code class="Dv">TCP_TXTLS_MODE</code>
socket option to toggle between <code class="Dv">TCP_TLS_MODE_SW</code> and
<code class="Dv">TCP_TLS_MODE_IFNET</code>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Receive"><a class="permalink" href="#Receive">Receive</a></h2>
<p class="Pp">Once TLS receive is enabled by a successful set of the
<code class="Dv">TCP_RXTLS_ENABLE</code> socket option, all data read from
the socket is returned as decrypted TLS records. Each received TLS record
must be read from the socket using <a class="Xr">recvmsg(2)</a>. Each
received TLS record will contain a <code class="Dv">TLS_GET_RECORD</code>
control message along with the decrypted payload. The control message
contains a <var class="Vt">struct tls_get_record</var> which includes fields
from the TLS record header. If an invalid or corrupted TLS record is
received, <a class="Xr">recvmsg(2)</a> will fail with one of the following
errors:</p>
<dl class="Bl-tag">
<dt>[<code class="Er">EINVAL</code>]</dt>
<dd>The version fields in a TLS record's header did not match the version
required by the <var class="Vt">struct tls_enable</var> structure used to
enable in-kernel TLS.</dd>
<dt>[<code class="Er">EMSGSIZE</code>]</dt>
<dd>A TLS record's length was either too small or too large.</dd>
<dt>[<code class="Er">EMSGSIZE</code>]</dt>
<dd>The connection was closed after sending a truncated TLS record.</dd>
<dt>[<code class="Er">EBADMSG</code>]</dt>
<dd>The TLS record failed to match the included authentication tag.</dd>
</dl>
<p class="Pp">The current TLS receive mode of a socket can be queried via the
<code class="Dv">TCP_RXTLS_MODE</code> socket option. At present, the mode
cannot be changed.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Sysctl_Nodes"><a class="permalink" href="#Sysctl_Nodes">Sysctl
Nodes</a></h2>
<p class="Pp"><code class="Nm">ktls</code> uses several sysctl nodes under the
<var class="Va">kern.ipc.tls</var> node. A few of them are described
below:</p>
<dl class="Bl-tag">
<dt id="kern.ipc.tls.enable"><var class="Va">kern.ipc.tls.enable</var></dt>
<dd>Determines if new kernel TLS sessions can be created.</dd>
<dt id="kern.ipc.tls.cbc_enable"><var class="Va">kern.ipc.tls.cbc_enable</var></dt>
<dd>Determines if new kernel TLS sessions with a cipher suite using AES-CBC
can be created.</dd>
<dt id="kern.ipc.tls.sw"><var class="Va">kern.ipc.tls.sw</var></dt>
<dd>A tree of nodes containing statistics for TLS sessions using
<code class="Dv">TCP_TLS_MODE_SW</code>.</dd>
<dt id="kern.ipc.tls.ifnet"><var class="Va">kern.ipc.tls.ifnet</var></dt>
<dd>A tree of nodes containing statistics for TLS sessions using
<code class="Dv">TCP_TLS_MODE_IFNET</code>.</dd>
<dt id="kern.ipc.tls.toe"><var class="Va">kern.ipc.tls.toe</var></dt>
<dd>A tree of nodes containing statistics for TLS sessions using
<code class="Dv">TCP_TLS_MODE_TOE</code>.</dd>
<dt id="kern.ipc.tls.stats"><var class="Va">kern.ipc.tls.stats</var></dt>
<dd>A tree of nodes containing various kernel TLS statistics.</dd>
</dl>
<p class="Pp">The <var class="Va">kern.ipc.mb_use_ext_pgs</var> sysctl controls
whether the kernel may use unmapped mbufs. They are required for TLS
transmit.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Supported_Hardware"><a class="permalink" href="#Supported_Hardware">Supported
Hardware</a></h2>
<p class="Pp">The <a class="Xr">cxgbe(4)</a> and <a class="Xr">mlx5en(4)</a>
drivers include support for the <code class="Dv">TCP_TLS_MODE_IFNET</code>
mode.</p>
<p class="Pp">The <a class="Xr">cxgbe(4)</a> driver includes support for the
<code class="Dv">TCP_TLS_MODE_TOE</code> mode.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Supported_Libraries"><a class="permalink" href="#Supported_Libraries">Supported
Libraries</a></h2>
<p class="Pp">OpenSSL 3.0 and later include support for
<code class="Nm">ktls</code>. The <var class="Fa">security/openssl*</var>
and <var class="Fa">security/gnutls</var> ports may also be built with
support for <code class="Nm">ktls</code> by enabling the
<code class="Dv">KTLS</code> option. OpenSSL in the base system includes
KTLS support when built with <code class="Dv">WITH_OPENSSL_KTLS</code>.</p>
<p class="Pp">Applications using a supported library should generally work with
<code class="Nm">ktls</code> without any changes provided they use standard
interfaces such as <a class="Xr">SSL_read(3)</a> and
<a class="Xr">SSL_write(3)</a>. Additional performance may be gained by the
use of <a class="Xr">SSL_sendfile(3)</a>.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION
NOTES</a></h1>
<p class="Pp"><code class="Nm">ktls</code> assumes the presence of a direct map
of physical memory when performing software encryption and decryption. As a
result, it is only supported on architectures with a direct map.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">cxgbe(4)</a>, <a class="Xr">mlx5en(4)</a>,
<a class="Xr">tcp(4)</a>, <a class="Xr">src.conf(5)</a>,
<a class="Xr">ifconfig(8)</a>, <a class="Xr">sysctl(8)</a>,
<a class="Xr">crypto(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">Kernel TLS first appeared in <span class="Ux">FreeBSD
13.0</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">October 31, 2024</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
