share/man/man4/ktls.4

   1 .\" Copyright (c) 2020, Chelsio Inc
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions are met:
   6 .\"
   7 .\" 1. Redistributions of source code must retain the above copyright notice,
   8 .\"    this list of conditions and the following disclaimer.
   9 .\"
  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.
  13 .\"
  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.
  17 .\"
  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.
  29 .\"
  30 .\" * Other names and brands may be claimed as the property of others.
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd November 25, 2020
  35 .Dt KTLS 4
  36 .Os
  37 .Sh NAME
  38 .Nm ktls
  39 .Nd kernel Transport Layer Security
  40 .Sh SYNOPSIS
  41 .Cd options KERN_TLS
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 facility allows the kernel to perform Transport Layer Security (TLS)
  46 framing on TCP sockets.
  47 With
  48 .Nm ,
  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
  52 .Dv TCP_TXTLS_ENABLE
  53 and
  54 .Dv TCP_RXTLS_ENABLE
  55 socket options.
  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
  61 direction.
  62 .Pp
  63 .Nm
  64 only permits the session keys to be set once in each direction.
  65 As a result,
  66 applications must disable rekeying when using
  67 .Nm .
  68 .Ss Modes
  69 .Nm
  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
  76 .Nm
  77 is not enabled.
  78 .It Dv TCP_TLS_MODE_SW
  79 TLS records are encrypted or decrypted in the kernel in the socket
  80 layer.
  81 Typically the encryption or decryption is performred in software,
  82 but it may also be performed by co-processors via
  83 .Xr crypto 9 .
  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 is encrypts TLS records as they are being transmitted,
  88 or decrypts received TLS records before providing them to the host.
  89 .Pp
  90 Network interfaces which support this feature will advertise the
  91 .Dv TXTLS4
  92 (for IPv4)
  93 and/or
  94 .Dv TXTLS6
  95 (for IPv6)
  96 capabilities as reported by
  97 .Xr ifconfig 8 .
  98 These capabilities can also be controlled by
  99 .Xr ifconfig 8 .
 100 .Pp
 101 If a network interface supports rate limiting
 102 (also known as packet pacing) for TLS offload,
 103 the interface will advertise the
 104 .Dv TXTLS_RTLMT
 105 capability.
 106 .It Dv TCP_TLS_MODE_TOE
 107 TLS records are encrypted by the NIC using a TCP offload engine (TOE).
 108 This is similar to
 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
 112 between TCP and TLS.
 113 .El
 114 .Ss Transmit
 115 Once TLS transmit is enabled by a successful set of the
 116 .Dv TCP_TXTLS_ENABLE
 117 socket option,
 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
 122 by
 123 .Xr sendmsg 2
 124 with the TLS record type set in a
 125 .Dv TLS_SET_RECORD_TYPE
 126 control message.
 127 The payload of this control message is a single byte holding the desired
 128 TLS record type.
 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
 132 fragments).
 133 .Pp
 134 TLS transmit requires the use of unmapped mbufs.
 135 Unmapped mbufs are not enabled by default, but can be enabled by
 136 setting the
 137 .Va kern.ipc.mb_use_ext_pgs
 138 sysctl node to 1.
 139 .Pp
 140 The current TLS transmit mode of a socket can be queried via the
 141 .Dv TCP_TXTLS_MODE
 142 socket option.
 143 A socket using TLS transmit offload can also set the
 144 .Dv TCP_TXTLS_MODE
 145 socket option to toggle between
 146 .Dv TCP_TLS_MODE_SW
 147 and
 148 .Dv TCP_TLS_MODE_IFNET .
 149 .Ss Receive
 150 Once TLS receive is enabled by a successful set of the
 151 .Dv TCP_RXTLS_ENABLE
 152 socket option,
 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
 155 .Xr recvmsg 2 .
 156 Each received TLS record will contain a
 157 .Dv TLS_GET_RECORD
 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,
 163 recvmsg 2
 164 will fail with one of the following errors:
 165 .Bl -tag -width Er
 166 .It Bq Er EINVAL
 167 The version fields in a TLS record's header did not match the version required
 168 by the
 169 .Vt struct tls_so_enable
 170 structure used to enable in-kernel TLS.
 171 .It Bq Er EMSGSIZE
 172 A TLS record's length was either too small or too large.
 173 .It Bq Er EMSGSIZE
 174 The connection was closed after sending a truncated TLS record.
 175 .It Bq Er EBADMSG
 176 The TLS record failed to match the included authentication tag.
 177 .El
 178 .Pp
 179 The current TLS receive mode of a socket can be queried via the
 180 .Dv TCP_RXTLS_MODE
 181 socket option.
 182 At present,
 183 the mode cannot be changed.
 184 .Ss Sysctl Nodes
 185 .Nm
 186 uses several sysctl nodes under the
 187 .Va kern.ipc.tls
 188 node.
 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
 195 can be created.
 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.
 207 .El
 208 .Ss Backends
 209 The base system includes a software backend for the
 210 .Dv TCP_TLS_MODE_SW
 211 mode which uses
 212 .Xr crypto 9
 213 to encrypt and decrypt TLS records.
 214 This backend can be enabled by loading the
 215 .Pa ktls_ocf.ko
 216 kernel module.
 217 .Pp
 218 The
 219 .Xr cxgbe 4
 220 and
 221 .Xr mlx5en 4
 222 drivers include support for the
 223 .Dv TCP_TLS_MODE_IFNET
 224 mode.
 225 .Pp
 226 The
 227 .Xr cxgbe 4
 228 driver includes support for the
 229 .Dv TCP_TLS_MODE_TOE
 230 mode.
 231 .Ss Supported Libraries
 232 OpenSSL 3.0 and later include support for
 233 .Nm .
 234 The
 235 .Fa devel/openssl
 236 port may also be built with support for
 237 .Nm
 238 by enabling the
 239 .Dv KTLS
 240 option .
 241 .Pp
 242 Applications using a supported library should generally work with
 243 .Nm
 244 without any changes provided they use standard interfaces such as
 245 .Xr SSL_read 3
 246 and
 247 .Xr SSL_write 3 .
 248 Additional performance may be gained by the use of
 249 .Xr SSL_sendfile 3 .
 250 .Sh IMPLEMENTATION NOTES
 251 .Nm
 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.
 255 .Sh SEE ALSO
 256 .Xr cxgbe 4 ,
 257 .Xr mlx5en 4 ,
 258 .Xr tcp 4 ,
 259 .Xr ifconfig 8 ,
 260 .Xr sysctl 8 ,
 261 .Xr crypto 9
 262 .Sh HISTORY
 263 Kernel TLS first appeared in
 264 .Fx 13.0 .