--- name: "ktls" section: "4" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/ktls" --- # ktls(4) kernel Transport Layer Security ## NAME **ktls** – kernel Transport Layer Security ## SYNOPSIS **options** **KERN\_TLS** ## DESCRIPTION The **ktls** facility allows the kernel to perform Transport Layer Security (TLS) framing on TCP sockets. With **ktls**, 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 TCP\_TXTLS\_ENABLE and TCP\_RXTLS\_ENABLE socket options. Both socket options accept a *struct* *tls\_enable* 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. **ktls** only permits the session keys to be set once in each direction. As a result, applications must disable rekeying when using **ktls**. ### Modes **ktls** 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: - TCP\_TLS\_MODE\_NONE **ktls** is not enabled. - TCP\_TLS\_MODE\_SW TLS records are encrypted or decrypted in the kernel in the socket layer via [crypto(9)](/crypto/9.md). Typically the encryption or decryption is performed in software, but it may also be performed by co-processors. - TCP\_TLS\_MODE\_IFNET 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. Network interfaces which support this feature will advertise the TXTLS4 (for IPv4) and/or TXTLS6 (for IPv6) capabilities as reported by [ifconfig(8)](/ifconfig/8.md). These capabilities can also be controlled by [ifconfig(8)](/ifconfig/8.md). If a network interface supports rate limiting (also known as packet pacing) for TLS offload, the interface will advertise the TXTLS\_RTLMT capability. - TCP\_TLS\_MODE\_TOE TLS records are encrypted by the NIC using a TCP offload engine (TOE). This is similar to TCP\_TLS\_MODE\_IFNET 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. ### Transmit Once TLS transmit is enabled by a successful set of the TCP\_TXTLS\_ENABLE 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 [sendmsg(2)](/sendmsg/2.md) with the TLS record type set in a TLS\_SET\_RECORD\_TYPE 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). The current TLS transmit mode of a socket can be queried via the TCP\_TXTLS\_MODE socket option. A socket using TLS transmit offload can also set the TCP\_TXTLS\_MODE socket option to toggle between TCP\_TLS\_MODE\_SW and TCP\_TLS\_MODE\_IFNET. ### Receive Once TLS receive is enabled by a successful set of the TCP\_RXTLS\_ENABLE 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 [recvmsg(2)](/recvmsg/2.md). Each received TLS record will contain a TLS\_GET\_RECORD control message along with the decrypted payload. The control message contains a *struct* *tls\_get\_record* which includes fields from the TLS record header. If an invalid or corrupted TLS record is received, [recvmsg(2)](/recvmsg/2.md) will fail with one of the following errors: - \[EINVAL\] The version fields in a TLS record's header did not match the version required by the *struct* *tls\_enable* structure used to enable in-kernel TLS. - \[EMSGSIZE\] A TLS record's length was either too small or too large. - \[EMSGSIZE\] The connection was closed after sending a truncated TLS record. - \[EBADMSG\] The TLS record failed to match the included authentication tag. The current TLS receive mode of a socket can be queried via the TCP\_RXTLS\_MODE socket option. At present, the mode cannot be changed. ### Sysctl Nodes **ktls** uses several sysctl nodes under the *kern.ipc.tls* node. A few of them are described below: - *kern.ipc.tls.enable* Determines if new kernel TLS sessions can be created. - *kern.ipc.tls.rx\_enable* Determines if new kernel TLS receive sessions can be created. - *kern.ipc.tls.cbc\_enable* Determines if new kernel TLS sessions with a cipher suite using AES-CBC can be created. - *kern.ipc.tls.sw* A tree of nodes containing statistics for TLS sessions using TCP\_TLS\_MODE\_SW. - *kern.ipc.tls.ifnet* A tree of nodes containing statistics for TLS sessions using TCP\_TLS\_MODE\_IFNET. - *kern.ipc.tls.toe* A tree of nodes containing statistics for TLS sessions using TCP\_TLS\_MODE\_TOE. - *kern.ipc.tls.stats* A tree of nodes containing various kernel TLS statistics. The *kern.ipc.mb\_use\_ext\_pgs* sysctl controls whether the kernel may use unmapped mbufs. They are required for TLS transmit. ### Supported Hardware The [cxgbe(4)](/cxgbe/4.md) and [mlx5en(4)](/mlx5en/4.md) drivers include support for the TCP\_TLS\_MODE\_IFNET mode. The [cxgbe(4)](/cxgbe/4.md) driver includes support for the TCP\_TLS\_MODE\_TOE mode. ### Supported Libraries OpenSSL 3.0 and later include support for **ktls**. The *security/openssl\** and *security/gnutls* ports may also be built with support for **ktls** by enabling the KTLS option. OpenSSL in the base system includes KTLS support when built with WITH\_OPENSSL\_KTLS. Applications using a supported library should generally work with **ktls** without any changes provided they use standard interfaces such as SSL\_read(3) and SSL\_write(3). Additional performance may be gained by the use of SSL\_sendfile(3). ## IMPLEMENTATION NOTES **ktls** 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. ## SEE ALSO [cxgbe(4)](/cxgbe/4.md), [mlx5en(4)](/mlx5en/4.md), [tcp(4)](/tcp/4.md), [src.conf(5)](/src.conf/5.md), [ifconfig(8)](/ifconfig/8.md), [sysctl(8)](/sysctl/8.md), [crypto(9)](/crypto/9.md) ## HISTORY Kernel TLS first appeared in FreeBSD 13.0.