d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add a manpage for kernel TLS.

Browse Source 
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
This commit is contained in:
John Baldwin 2020-11-25 23:17:23 +00:00
parent 2e51c2bfd1
commit d1e0552937
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=368040
3 changed files with 276 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
share/man/man4/Makefile
View File

@ -250,6 +250,7 @@ MAN= aac.4 \
kld.4 \
ksyms.4 \
ksz8995ma.4 \
ktls.4 \
ktr.4 \
kue.4 \
lagg.4 \

264
share/man/man4/ktls.4 Normal file
View File

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

87
share/man/man4/tcp.4
View File

@ -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,86 +300,20 @@ Each dropped segment is taken into account in the TCP protocol statistics.
.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.
.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 .
See
.Xr ktls 4
for more details.
.El
.Pp
The option level for the
@ -770,6 +704,7 @@ when trying to use a TCP function block that is not available;
.Xr inet 4 ,
.Xr intro 4 ,
.Xr ip 4 ,
.Xr ktls 4 ,
.Xr mod_cc 4 ,
.Xr siftr 4 ,
.Xr syncache 4 ,