Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
KTLS(4)		       FreeBSD Kernel Interfaces Manual		       KTLS(4)

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 ne-
     gotiated, 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	ses-
     sion 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 di-
     rection.  The available modes are:

     TCP_TLS_MODE_NONE	    ktls is not	enabled.

     TCP_TLS_MODE_SW	    TLS	records	are encrypted or decrypted in the ker-
			    nel	in the socket layer.  Typically	the encryption
			    or decryption is performed in software, but	it may
			    also be performed by co-processors via crypto(9).

     TCP_TLS_MODE_IFNET	    TLS	records	are encrypted or decrypted by the net-
			    work interface card	(NIC).	In this	mode, the net-
			    work stack does not	work with encrypted data.  In-
			    stead, 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).
			    These capabilities can also	be controlled by
			    ifconfig(8).

			    If a network interface supports rate limiting
			    (also known	as packet pacing) for TLS offload, the
			    interface will advertise the TXTLS_RTLMT capabil-
			    ity.

     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)	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).

     TLS transmit requires the use of unmapped mbufs.  Unmapped	mbufs are not
     enabled by	default, but can be enabled by setting the
     kern.ipc.mb_use_ext_pgs sysctl node to 1.

     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).  Each received	TLS record will	contain	a TLS_GET_RECORD con-
     trol message along	with the decrypted payload.  The control message con-
     tains a struct tls_get_record which includes fields from the TLS record
     header.  If an invalid or corrupted TLS record is received, recvmsg(2)
     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 authenti-
			cation 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.cbc_enable  Determines if new	kernel TLS sessions with a ci-
			      pher 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.

   Backends
     The base system includes a	software backend for the TCP_TLS_MODE_SW mode
     which uses	crypto(9) to encrypt and decrypt TLS records.  This backend
     can be enabled by loading the ktls_ocf.ko kernel module.

     The cxgbe(4) and mlx5en(4)	drivers	include	support	for the
     TCP_TLS_MODE_IFNET	mode.

     The cxgbe(4) driver includes support for the TCP_TLS_MODE_TOE mode.

   Supported Libraries
     OpenSSL 3.0 and later include support for ktls.  The devel/openssl	port
     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 per-
     forming software encryption and decryption.  As a result, it is only sup-
     ported on architectures with a direct map.

SEE ALSO
     cxgbe(4), mlx5en(4), tcp(4), src.conf(5), ifconfig(8), sysctl(8),
     crypto(9)

HISTORY
     Kernel TLS	first appeared in FreeBSD 13.0.

FreeBSD	13.0			 March 8, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ktls&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help