svn commit: r368040 - head/share/man/man4

John Baldwin jhb at FreeBSD.org
Wed Nov 25 23:17:24 UTC 2020 

Author: jhb
Date: Wed Nov 25 23:17:23 2020
New Revision: 368040
URL: https://svnweb.freebsd.org/changeset/base/368040

Log:
  Add a manpage for kernel TLS.
  
  This subsumes some of the content from tcp(4) describing the socket
  options but also adds additional notes.
  
  Reviewed by:	gallatin, hselasky
  Sponsored by:	Chelsio Communications
  Differential Revision:	https://reviews.freebsd.org/D27272

Added:
  head/share/man/man4/ktls.4   (contents, props changed)
Modified:
  head/share/man/man4/Makefile
  head/share/man/man4/tcp.4

Modified: head/share/man/man4/Makefile
==============================================================================
--- head/share/man/man4/Makefile	Wed Nov 25 22:53:21 2020	(r368039)
+++ head/share/man/man4/Makefile	Wed Nov 25 23:17:23 2020	(r368040)
@@ -250,6 +250,7 @@ MAN=	aac.4 \
 	kld.4 \
 	ksyms.4 \
 	ksz8995ma.4 \
+	ktls.4 \
 	ktr.4 \
 	kue.4 \
 	lagg.4 \

Added: head/share/man/man4/ktls.4
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man4/ktls.4	Wed Nov 25 23:17:23 2020	(r368040)
@@ -0,0 +1,264 @@
+.\" Copyright (c) 2020, Chelsio Inc
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright notice,
+.\"    this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" 3. Neither the name of the Chelsio Inc nor the names of its
+.\"    contributors may be used to endorse or promote products derived from
+.\"    this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" * Other names and brands may be claimed as the property of others.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 25, 2020
+.Dt KTLS 4
+.Os
+.Sh NAME
+.Nm ktls
+.Nd kernel Transport Layer Security
+.Sh SYNOPSIS
+.Cd options KERN_TLS
+.Sh DESCRIPTION
+The
+.Nm
+facility allows the kernel to perform Transport Layer Security (TLS)
+framing on TCP sockets.
+With
+.Nm ,
+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
+.Dv TCP_TXTLS_ENABLE
+and
+.Dv TCP_RXTLS_ENABLE
+socket options.
+Both socket options accept a
+.Vt struct tls_so_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.
+.Pp
+.Nm
+only permits the session keys to be set once in each direction.
+As a result,
+applications must disable rekeying when using
+.Nm .
+.Ss Modes
+.Nm
+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:
+.Bl -tag -width "Dv TCP_TLS_MODE_IFNET"
+.It Dv TCP_TLS_MODE_NONE
+.Nm
+is not enabled.
+.It Dv TCP_TLS_MODE_SW
+TLS records are encrypted or decrypted in the kernel in the socket
+layer.
+Typically the encryption or decryption is performred in software,
+but it may also be performed by co-processors via
+.Xr crypto 9 .
+.It Dv 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 is encrypts TLS records as they are being transmitted,
+or decrypts received TLS records before providing them to the host.
+.Pp
+Network interfaces which support this feature will advertise the
+.Dv TXTLS4
+(for IPv4)
+and/or
+.Dv TXTLS6
+(for IPv6)
+capabilities as reported by
+.Xr ifconfig 8 .
+These capabilities can also be controlled by
+.Xr ifconfig 8 .
+.Pp
+If a network interface supports rate limiting
+(also known as packet pacing) for TLS offload,
+the interface will advertise the
+.Dv TXTLS_RTLMT
+capability.
+.It Dv TCP_TLS_MODE_TOE
+TLS records are encrypted by the NIC using a TCP offload engine (TOE).
+This is similar to
+.Dv 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.
+.El
+.Ss Transmit
+Once TLS transmit is enabled by a successful set of the
+.Dv 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
+.Xr sendmsg 2
+with the TLS record type set in a
+.Dv 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).
+.Pp
+TLS transmit requires the use of unmapped mbufs.
+Unmapped mbufs are not enabled by default, but can be enabled by
+setting the
+.Va kern.ipc.mb_use_ext_pgs
+sysctl node to 1.
+.Pp
+The current TLS transmit mode of a socket can be queried via the
+.Dv TCP_TXTLS_MODE
+socket option.
+A socket using TLS transmit offload can also set the
+.Dv TCP_TXTLS_MODE
+socket option to toggle between
+.Dv TCP_TLS_MODE_SW
+and
+.Dv TCP_TLS_MODE_IFNET .
+.Ss Receive
+Once TLS receive is enabled by a successful set of the
+.Dv 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
+.Xr recvmsg 2 .
+Each received TLS record will contain a
+.Dv TLS_GET_RECORD
+control message along with the decrypted payload.
+The control message contains a
+.Vt 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:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The version fields in a TLS record's header did not match the version required
+by the
+.Vt struct tls_so_enable
+structure used to enable in-kernel TLS.
+.It Bq Er EMSGSIZE
+A TLS record's length was either too small or too large.
+.It Bq Er EMSGSIZE
+The connection was closed after sending a truncated TLS record.
+.It Bq Er EBADMSG
+The TLS record failed to match the included authentication tag.
+.El
+.Pp
+The current TLS receive mode of a socket can be queried via the
+.Dv TCP_RXTLS_MODE
+socket option.
+At present,
+the mode cannot be changed.
+.Ss Sysctl Nodes
+.Nm
+uses several sysctl nodes under the
+.Va kern.ipc.tls
+node.
+A few of them are described below:
+.Bl -tag -width ".Va kern.ipc.tls.cbc_enable"
+.It Va kern.ipc.tls.enable
+Determines if new kernel TLS sessions can be created.
+.It Va kern.ipc.tls.cbc_enable
+Determines if new kernel TLS sessions with a cipher suite using AES-CBC
+can be created.
+.It Va kern.ipc.tls.sw
+A tree of nodes containing statistics for TLS sessions using
+.Dv TCP_TLS_MODE_SW .
+.It Va kern.ipc.tls.ifnet
+A tree of nodes containing statistics for TLS sessions using
+.Dv TCP_TLS_MODE_IFNET .
+.It Va kern.ipc.tls.toe
+A tree of nodes containing statistics for TLS sessions using
+.Dv TCP_TLS_MODE_TOE .
+.It Va kern.ipc.tls.stats
+A tree of nodes containing various kernel TLS statistics.
+.El
+.Ss Backends
+The base system includes a software backend for the
+.Dv TCP_TLS_MODE_SW
+mode which uses
+.Xr crypto 9
+to encrypt and decrypt TLS records.
+This backend can be enabled by loading the
+.Pa ktls_ocf.ko
+kernel module.
+.Pp
+The
+.Xr cxgbe 4
+and
+.Xr mlx5en 4
+drivers include support for the
+.Dv TCP_TLS_MODE_IFNET
+mode.
+.Pp
+The
+.Xr cxgbe 4
+driver includes support for the
+.Dv TCP_TLS_MODE_TOE
+mode.
+.Ss Supported Libraries
+OpenSSL 3.0 and later include support for
+.Nm .
+The
+.Fa devel/openssl
+port may also be built with support for
+.Nm
+by enabling the
+.Dv KTLS
+option .
+.Pp
+Applications using a supported library should generally work with
+.Nm
+without any changes provided they use standard interfaces such as
+.Xr SSL_read 3
+and
+.Xr SSL_write 3 .
+Additional performance may be gained by the use of
+.Xr SSL_sendfile 3 .
+.Sh IMPLEMENTATION NOTES
+.Nm
+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.
+.Sh SEE ALSO
+.Xr cxgbe 4 ,
+.Xr mlx5en 4 ,
+.Xr tcp 4 ,
+.Xr ifconfig 8 ,
+.Xr sysctl 8 ,
+.Xr crypto 9
+.Sh HISTORY
+Kernel TLS first appeared in
+.Fx 13.0 .

Modified: head/share/man/man4/tcp.4
==============================================================================
--- head/share/man/man4/tcp.4	Wed Nov 25 22:53:21 2020	(r368039)
+++ head/share/man/man4/tcp.4	Wed Nov 25 23:17:23 2020	(r368040)
@@ -34,7 +34,7 @@
 .\"     From: @(#)tcp.4	8.1 (Berkeley) 6/5/93
 .\" $FreeBSD$
 .\"
-.Dd July 23, 2020
+.Dd November 25, 2020
 .Dt TCP 4
 .Os
 .Sh NAME
@@ -300,88 +300,22 @@ Each dropped segment is taken into account in the TCP 
 .It Dv TCP_TXTLS_ENABLE
 Enable in-kernel Transport Layer Security (TLS) for data written to this
 socket.
-The
-.Vt struct tls_so_enable
-argument defines the encryption and authentication algorithms and keys
-used to encrypt the socket data as well as the maximum TLS record
-payload size.
-.Pp
-All data written to this socket will be encapsulated in TLS records
-and subsequently encrypted.
-By default all data written to this socket is treated as application data.
-Individual TLS records with a type other than application data
-(for example, handshake messages),
-may be transmitted by invoking
-.Xr sendmsg 2
-with a custom TLS record type set in a
-.Dv TLS_SET_RECORD_TYPE
-control message.
-The payload of this control message is a single byte holding the desired
-TLS record type.
-.Pp
-At present, only a single transmit key may be set on a socket.
-As such, users of this option must disable rekeying.
+See
+.Xr ktls 4
+for more details.
 .It Dv TCP_TXTLS_MODE
 The integer argument can be used to get or set the current TLS transmit mode
 of a socket.
-Setting the mode can only used to toggle between software and NIC TLS after
-TLS has been initially enabled via the
-.Dv TCP_TXTLS_ENABLE
-option.
-The available modes are:
-.Bl -tag -width "Dv TCP_TLS_MODE_IFNET"
-.It Dv TCP_TLS_MODE_NONE
-In-kernel TLS framing and encryption is not enabled for this socket.
-.It Dv TCP_TLS_MODE_SW
-TLS records are encrypted by the kernel prior to placing the data in the
-socket buffer.
-Typically this encryption is performed in software.
-.It Dv TCP_TLS_MODE_IFNET
-TLS records are encrypted by the network interface card (NIC).
-.It Dv TCP_TLS_MODE_TOE
-TLS records are encrypted by the NIC using a TCP offload engine (TOE).
-.El
+See
+.Xr ktls 4
+for more details.
 .It Dv TCP_RXTLS_ENABLE
 Enable in-kernel TLS for data read from this socket.
-The
-.Vt struct tls_so_enable
-argument defines the encryption and authentication algorithms and keys
-used to decrypt the socket data.
-.Pp
-Each received TLS record must be read from the socket using
-.Xr recvmsg 2 .
-Each received TLS record will contain a
-.Dv TLS_GET_RECORD
-control message along with the decrypted payload.
-The control message contains a
-.Vt 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:
-.Bl -tag -width Er
-.It Bq Er EINVAL
-The version fields in a TLS record's header did not match the version required
-by the
-.Vt struct tls_so_enable
-structure used to enable in-kernel TLS.
-.It Bq Er EMSGSIZE
-A TLS record's length was either too small or too large.
-.It Bq Er EMSGSIZE
-The connection was closed after sending a truncated TLS record.
-.It Bq Er EBADMSG
-The TLS record failed to match the included authentication tag.
+See
+.Xr ktls 4
+for more details.
 .El
 .Pp
-At present, only a single receive key may be set on a socket.
-As such, users of this option must disable rekeying.
-.It Dv TCP_RXTLS_MODE
-The integer argument can be used to get the current TLS receive mode
-of a socket.
-The available modes are the same as for
-.Dv TCP_TXTLS_MODE .
-.El
-.Pp
 The option level for the
 .Xr setsockopt 2
 call is the protocol number for
@@ -770,6 +704,7 @@ when trying to use a TCP function block that is not av
 .Xr inet 4 ,
 .Xr intro 4 ,
 .Xr ip 4 ,
+.Xr ktls 4 ,
 .Xr mod_cc 4 ,
 .Xr siftr 4 ,
 .Xr syncache 4 ,

More information about the svn-src-all mailing list