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 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_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 134The current TLS transmit mode of a socket can be queried via the 135.Dv TCP_TXTLS_MODE 136socket option. 137A socket using TLS transmit offload can also set the 138.Dv TCP_TXTLS_MODE 139socket option to toggle between 140.Dv TCP_TLS_MODE_SW 141and 142.Dv TCP_TLS_MODE_IFNET . 143.Ss Receive 144Once TLS receive is enabled by a successful set of the 145.Dv TCP_RXTLS_ENABLE 146socket option, 147all data read from the socket is returned as decrypted TLS records. 148Each received TLS record must be read from the socket using 149.Xr recvmsg 2 . 150Each received TLS record will contain a 151.Dv TLS_GET_RECORD 152control message along with the decrypted payload. 153The control message contains a 154.Vt struct tls_get_record 155which includes fields from the TLS record header. 156If an invalid or corrupted TLS record is received, 157.Xr recvmsg 2 158will fail with one of the following errors: 159.Bl -tag -width Er 160.It Bq Er EINVAL 161The version fields in a TLS record's header did not match the version required 162by the 163.Vt struct tls_enable 164structure used to enable in-kernel TLS. 165.It Bq Er EMSGSIZE 166A TLS record's length was either too small or too large. 167.It Bq Er EMSGSIZE 168The connection was closed after sending a truncated TLS record. 169.It Bq Er EBADMSG 170The TLS record failed to match the included authentication tag. 171.El 172.Pp 173The current TLS receive mode of a socket can be queried via the 174.Dv TCP_RXTLS_MODE 175socket option. 176At present, 177the mode cannot be changed. 178.Ss Sysctl Nodes 179.Nm 180uses several sysctl nodes under the 181.Va kern.ipc.tls 182node. 183A few of them are described below: 184.Bl -tag -width ".Va kern.ipc.tls.cbc_enable" 185.It Va kern.ipc.tls.enable 186Determines if new kernel TLS sessions can be created. 187.It Va kern.ipc.tls.cbc_enable 188Determines if new kernel TLS sessions with a cipher suite using AES-CBC 189can be created. 190.It Va kern.ipc.tls.sw 191A tree of nodes containing statistics for TLS sessions using 192.Dv TCP_TLS_MODE_SW . 193.It Va kern.ipc.tls.ifnet 194A tree of nodes containing statistics for TLS sessions using 195.Dv TCP_TLS_MODE_IFNET . 196.It Va kern.ipc.tls.toe 197A tree of nodes containing statistics for TLS sessions using 198.Dv TCP_TLS_MODE_TOE . 199.It Va kern.ipc.tls.stats 200A tree of nodes containing various kernel TLS statistics. 201.El 202.Pp 203The 204.Va kern.ipc.mb_use_ext_pgs 205sysctl controls whether the kernel may use unmapped mbufs. 206They are required for TLS transmit. 207.Ss Backends 208The base system includes a software backend for the 209.Dv TCP_TLS_MODE_SW 210mode which uses 211.Xr crypto 9 212to encrypt and decrypt TLS records. 213This backend can be enabled by loading the 214.Pa ktls_ocf.ko 215kernel module. 216.Pp 217The 218.Xr cxgbe 4 219and 220.Xr mlx5en 4 221drivers include support for the 222.Dv TCP_TLS_MODE_IFNET 223mode. 224.Pp 225The 226.Xr cxgbe 4 227driver includes support for the 228.Dv TCP_TLS_MODE_TOE 229mode. 230.Ss Supported Libraries 231OpenSSL 3.0 and later include support for 232.Nm . 233The 234.Fa devel/openssl 235port may also be built with support for 236.Nm 237by enabling the 238.Dv KTLS 239option. 240OpenSSL in the base system includes KTLS support when built with 241.Dv WITH_OPENSSL_KTLS . 242.Pp 243Applications using a supported library should generally work with 244.Nm 245without any changes provided they use standard interfaces such as 246.Xr SSL_read 3 247and 248.Xr SSL_write 3 . 249Additional performance may be gained by the use of 250.Xr SSL_sendfile 3 . 251.Sh IMPLEMENTATION NOTES 252.Nm 253assumes the presence of a direct map of physical memory when performing 254software encryption and decryption. 255As 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 265Kernel TLS first appeared in 266.Fx 13.0 . 267