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 December 1, 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 43The 44.Nm 45facility allows the kernel to perform Transport Layer Security (TLS) 46framing on TCP sockets. 47With 48.Nm , 49the initial handshake for a socket using TLS is performed in userland. 50Once the session keys are negotiated, 51they are provided to the kernel via the 52.Dv TCP_TXTLS_ENABLE 53and 54.Dv TCP_RXTLS_ENABLE 55socket options. 56Both socket options accept a 57.Vt struct tls_so_enable 58structure as their argument. 59The members of this structure describe the cipher suite used for the 60TLS session and provide the session keys used for the respective 61direction. 62.Pp 63.Nm 64only permits the session keys to be set once in each direction. 65As a result, 66applications must disable rekeying when using 67.Nm . 68.Ss Modes 69.Nm 70can operate in different modes. 71A given socket may use different modes for transmit and receive, 72or a socket may only offload a single direction. 73The available modes are: 74.Bl -tag -width "Dv TCP_TLS_MODE_IFNET" 75.It Dv TCP_TLS_MODE_NONE 76.Nm 77is not enabled. 78.It Dv TCP_TLS_MODE_SW 79TLS records are encrypted or decrypted in the kernel in the socket 80layer. 81Typically the encryption or decryption is performed in software, 82but it may also be performed by co-processors via 83.Xr crypto 9 . 84.It Dv TCP_TLS_MODE_IFNET 85TLS records are encrypted or decrypted by the network interface card (NIC). 86In this mode, the network stack does not work with encrypted data. 87Instead, the NIC encrypts TLS records as they are being transmitted, 88or decrypts received TLS records before providing them to the host. 89.Pp 90Network interfaces which support this feature will advertise the 91.Dv TXTLS4 92(for IPv4) 93and/or 94.Dv TXTLS6 95(for IPv6) 96capabilities as reported by 97.Xr ifconfig 8 . 98These capabilities can also be controlled by 99.Xr ifconfig 8 . 100.Pp 101If a network interface supports rate limiting 102(also known as packet pacing) for TLS offload, 103the interface will advertise the 104.Dv TXTLS_RTLMT 105capability. 106.It Dv TCP_TLS_MODE_TOE 107TLS records are encrypted by the NIC using a TCP offload engine (TOE). 108This is similar to 109.Dv TCP_TLS_MODE_IFNET 110in that the network stack does not work with encrypted data. 111However, this mode works in tandem with a TOE to handle interactions 112between TCP and TLS. 113.El 114.Ss Transmit 115Once TLS transmit is enabled by a successful set of the 116.Dv TCP_TXTLS_ENABLE 117socket option, 118all data written on the socket is stored in TLS records and encrypted. 119Most data is transmitted in application layer TLS records, 120and the kernel chooses how to partition data among TLS records. 121Individual TLS records with a fixed length and record type can be sent 122by 123.Xr sendmsg 2 124with the TLS record type set in a 125.Dv TLS_SET_RECORD_TYPE 126control message. 127The payload of this control message is a single byte holding the desired 128TLS record type. 129This can be used to send TLS records with a type other than 130application data (for example, handshake messages) or to send 131application data records with specific contents (for example, empty 132fragments). 133.Pp 134TLS transmit requires the use of unmapped mbufs. 135Unmapped mbufs are not enabled by default, but can be enabled by 136setting the 137.Va kern.ipc.mb_use_ext_pgs 138sysctl node to 1. 139.Pp 140The current TLS transmit mode of a socket can be queried via the 141.Dv TCP_TXTLS_MODE 142socket option. 143A socket using TLS transmit offload can also set the 144.Dv TCP_TXTLS_MODE 145socket option to toggle between 146.Dv TCP_TLS_MODE_SW 147and 148.Dv TCP_TLS_MODE_IFNET . 149.Ss Receive 150Once TLS receive is enabled by a successful set of the 151.Dv TCP_RXTLS_ENABLE 152socket option, 153all data read from the socket is returned as decrypted TLS records. 154Each received TLS record must be read from the socket using 155.Xr recvmsg 2 . 156Each received TLS record will contain a 157.Dv TLS_GET_RECORD 158control message along with the decrypted payload. 159The control message contains a 160.Vt struct tls_get_record 161which includes fields from the TLS record header. 162If an invalid or corrupted TLS record is received, 163recvmsg 2 164will fail with one of the following errors: 165.Bl -tag -width Er 166.It Bq Er EINVAL 167The version fields in a TLS record's header did not match the version required 168by the 169.Vt struct tls_so_enable 170structure used to enable in-kernel TLS. 171.It Bq Er EMSGSIZE 172A TLS record's length was either too small or too large. 173.It Bq Er EMSGSIZE 174The connection was closed after sending a truncated TLS record. 175.It Bq Er EBADMSG 176The TLS record failed to match the included authentication tag. 177.El 178.Pp 179The current TLS receive mode of a socket can be queried via the 180.Dv TCP_RXTLS_MODE 181socket option. 182At present, 183the mode cannot be changed. 184.Ss Sysctl Nodes 185.Nm 186uses several sysctl nodes under the 187.Va kern.ipc.tls 188node. 189A few of them are described below: 190.Bl -tag -width ".Va kern.ipc.tls.cbc_enable" 191.It Va kern.ipc.tls.enable 192Determines if new kernel TLS sessions can be created. 193.It Va kern.ipc.tls.cbc_enable 194Determines if new kernel TLS sessions with a cipher suite using AES-CBC 195can be created. 196.It Va kern.ipc.tls.sw 197A tree of nodes containing statistics for TLS sessions using 198.Dv TCP_TLS_MODE_SW . 199.It Va kern.ipc.tls.ifnet 200A tree of nodes containing statistics for TLS sessions using 201.Dv TCP_TLS_MODE_IFNET . 202.It Va kern.ipc.tls.toe 203A tree of nodes containing statistics for TLS sessions using 204.Dv TCP_TLS_MODE_TOE . 205.It Va kern.ipc.tls.stats 206A tree of nodes containing various kernel TLS statistics. 207.El 208.Ss Backends 209The base system includes a software backend for the 210.Dv TCP_TLS_MODE_SW 211mode which uses 212.Xr crypto 9 213to encrypt and decrypt TLS records. 214This backend can be enabled by loading the 215.Pa ktls_ocf.ko 216kernel module. 217.Pp 218The 219.Xr cxgbe 4 220and 221.Xr mlx5en 4 222drivers include support for the 223.Dv TCP_TLS_MODE_IFNET 224mode. 225.Pp 226The 227.Xr cxgbe 4 228driver includes support for the 229.Dv TCP_TLS_MODE_TOE 230mode. 231.Ss Supported Libraries 232OpenSSL 3.0 and later include support for 233.Nm . 234The 235.Fa devel/openssl 236port may also be built with support for 237.Nm 238by enabling the 239.Dv KTLS 240option . 241.Pp 242Applications using a supported library should generally work with 243.Nm 244without any changes provided they use standard interfaces such as 245.Xr SSL_read 3 246and 247.Xr SSL_write 3 . 248Additional performance may be gained by the use of 249.Xr SSL_sendfile 3 . 250.Sh IMPLEMENTATION NOTES 251.Nm 252assumes the presence of a direct map of physical memory when performing 253software encryption and decryption. 254As 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 263Kernel TLS first appeared in 264.Fx 13.0 . 265