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 May 26, 2021
  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_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 performed 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 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 The current TLS transmit mode of a socket can be queried via the
 135 .Dv TCP_TXTLS_MODE
 136 socket option.
 137 A socket using TLS transmit offload can also set the
 138 .Dv TCP_TXTLS_MODE
 139 socket option to toggle between
 140 .Dv TCP_TLS_MODE_SW
 141 and
 142 .Dv TCP_TLS_MODE_IFNET .
 143 .Ss Receive
 144 Once TLS receive is enabled by a successful set of the
 145 .Dv TCP_RXTLS_ENABLE
 146 socket option,
 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
 149 .Xr recvmsg 2 .
 150 Each received TLS record will contain a
 151 .Dv TLS_GET_RECORD
 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,
 157 .Xr recvmsg 2
 158 will fail with one of the following errors:
 159 .Bl -tag -width Er
 160 .It Bq Er EINVAL
 161 The version fields in a TLS record's header did not match the version required
 162 by the
 163 .Vt struct tls_enable
 164 structure used to enable in-kernel TLS.
 165 .It Bq Er EMSGSIZE
 166 A TLS record's length was either too small or too large.
 167 .It Bq Er EMSGSIZE
 168 The connection was closed after sending a truncated TLS record.
 169 .It Bq Er EBADMSG
 170 The TLS record failed to match the included authentication tag.
 171 .El
 172 .Pp
 173 The current TLS receive mode of a socket can be queried via the
 174 .Dv TCP_RXTLS_MODE
 175 socket option.
 176 At present,
 177 the mode cannot be changed.
 178 .Ss Sysctl Nodes
 179 .Nm
 180 uses several sysctl nodes under the
 181 .Va kern.ipc.tls
 182 node.
 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
 189 can be created.
 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.
 201 .El
 202 .Pp
 203 The
 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 Backends
 208 The base system includes a software backend for the
 209 .Dv TCP_TLS_MODE_SW
 210 mode which uses
 211 .Xr crypto 9
 212 to encrypt and decrypt TLS records.
 213 This backend can be enabled by loading the
 214 .Pa ktls_ocf.ko
 215 kernel module.
 216 .Pp
 217 The
 218 .Xr cxgbe 4
 219 and
 220 .Xr mlx5en 4
 221 drivers include support for the
 222 .Dv TCP_TLS_MODE_IFNET
 223 mode.
 224 .Pp
 225 The
 226 .Xr cxgbe 4
 227 driver includes support for the
 228 .Dv TCP_TLS_MODE_TOE
 229 mode.
 230 .Ss Supported Libraries
 231 OpenSSL 3.0 and later include support for
 232 .Nm .
 233 The
 234 .Fa devel/openssl
 235 port may also be built with support for
 236 .Nm
 237 by enabling the
 238 .Dv KTLS
 239 option.
 240 OpenSSL in the base system includes KTLS support when built with
 241 .Dv WITH_OPENSSL_KTLS .
 242 .Pp
 243 Applications using a supported library should generally work with
 244 .Nm
 245 without any changes provided they use standard interfaces such as
 246 .Xr SSL_read 3
 247 and
 248 .Xr SSL_write 3 .
 249 Additional performance may be gained by the use of
 250 .Xr SSL_sendfile 3 .
 251 .Sh IMPLEMENTATION NOTES
 252 .Nm
 253 assumes the presence of a direct map of physical memory when performing
 254 software encryption and decryption.
 255 As a result, it is only supported on architectures with a direct map.
 256 .Sh SEE ALSO
 257 .Xr cxgbe 4 ,
 258 .Xr mlx5en 4 ,
 259 .Xr tcp 4 ,
 260 .Xr src.conf 5 ,
 261 .Xr ifconfig 8 ,
 262 .Xr sysctl 8 ,
 263 .Xr crypto 9
 264 .Sh HISTORY
 265 Kernel TLS first appeared in
 266 .Fx 13.0 .