NVIDIA MLNX_OFED Documentation Rev 5.8-1.1.2.1 LTS
Linux Kernel Upstream Release Notes v5.17

Kernel Transport Layer Security (kTLS) Offloads

Warning

This feature is supported on ConnectX-6 Dx crypto cards only.

Transport Layer Security (TLS) is a widely-deployed protocol used for securing TCP connections on the Internet. TLS is also a required feature for HTTP/2, the latest web standard. Kernel implementation of TLS (kTLS) provides new opportunities for offloading the protocol into the hardware.

TLS data-path offload allows the NIC to accelerate encryption, decryption and authentication of AES-GCM. TLS offload handles data as it goes through the device without storing any data, but only updating context. If the packet cannot be encrypted/decrypted by the device, then a software fallback handles the packet.

To avoid unnecessary complexity in the kernel, the TLS handshake is kept in the user space. A full TLS connection using the socket is done using the following scheme:

  1. Call connect() or accept() on a standard TCP file descriptor.

  2. Use a user space TLS library to complete a handshake.

  3. Create a new KTLS socket file descriptor.

  4. Extract the TLS Initialization Vectors (IVs), session keys, and sequence IDs from the TLS library. Use the setsockopt function on the kTLS file descriptor (FD) to pass them to the kernel.

  5. Use standard read(), write(), sendfile() and splice() system calls on the KTLS FD.

Drivers can offer Tx and Rx packet encryption/decryption offload from the kernel into the NIC hardware. Upon receipt of a non-data TLS message (a control message), the kTLS socket returns an error, and the message is left on the original TCP socket instead. The kTLS socket is automatically unattached. Transfer of control back to the original encrypted FD is done by calling getsockopt to receive the current sequence numbers, and inserting them into the TLS library.

For support in the kernel, make sure the following flags are set as follows.

  • CONFIG_TLS=y

  • CONFIG_TLS_DEVICE=y | m

Warning

For kTLS Tx device offloads with OFED drivers, kernel TLS module (kernel/net/tls) must be aligned to kernel v5.3 and above.

For kTLS Rx device offloads with OFED drivers, kernel TLS module (kernel/net/tls) must be aligned to kernel v5.9 and above.

Procedure_Heading_Icon-version-1-modificationdate-1701069323227-api-v2.PNG

To enable kTLS Tx offload, run:

Copy
Copied!
            

ethtool -K <ifs> tls-hw-tx-offload on

Copy
Copied!
            

ethtool -K <ifs> tls-hw-rx-offload on

For further information on TLS offloads, please visit the following kernel documentation:

OpenSSL version 3.0.0 or above is required to support kTLS TX/RX offloads.

Supported OpenSSL version is available to download from distro packages, or can be downloaded and compiled from the OpenSSL github.

© Copyright 2023, NVIDIA. Last updated on Nov 27, 2023.