Update KTLS documentation

KTLS support has been changed to be off by default, and configuration is
via a single "option" rather two "modes". Documentation is updated
accordingly.

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14799)

diff --git a/CHANGES.md b/CHANGES.md
index 581fda0c96c0853f936c66fecff42f28a4ae9235..c85d106765b9b410f98df9b46e9d4b084b4744be 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,12 @@ OpenSSL 3.0
 
 ### Changes between 1.1.1 and 3.0 [xx XXX xxxx]
 
+ * Added support for Kernel TLS (KTLS). In order to use KTLS, support for it
+   must be compiled in using the "enable-ktls" compile time option. It must
+   also be enabled at run time using the SSL_OP_ENABLE_KTLS option.
+
+   *Boris Pismenny, John Baldwin and Andrew Gallatin*
+
  * A public key check is now performed during EVP_PKEY_derive_set_peer().
    Previously DH was internally doing this during EVP_PKEY_derive().
    To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0). This

diff --git a/NEWS.md b/NEWS.md
index 923a7130870558b3fa5f5f3355d4001c25da4003..c5811b9bde69f9db0aab897c65ef6e02c1c3c23f 100644 (file)
--- a/NEWS.md
+++ b/NEWS.md
@@ -20,6 +20,7 @@ OpenSSL 3.0
 
 ### Major changes between OpenSSL 1.1.1 and OpenSSL 3.0 [under development]
 
+  * Added suport for Kernel TLS (KTLS)
   * Changed the license to the Apache License v2.0.
   * Moved all variations of the EVP ciphers CAST5, BF, IDEA, SEED, RC2,
     RC4, RC5, and DES to the legacy provider.

diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod
index 97ebff047f2d04ce43074657d0135cfe07d69dd3..3fd1924de6d63a541458f1e8656529e935f9b8fb 100644 (file)
--- a/doc/man3/SSL_CONF_cmd.pod
+++ b/doc/man3/SSL_CONF_cmd.pod
@@ -524,6 +524,10 @@ B<CANames>: use CA names extension, enabled by
 default. Inverse of B<SSL_OP_DISABLE_TLSEXT_CA_NAMES>: that is,
 B<-CANames> is the same as setting B<SSL_OP_DISABLE_TLSEXT_CA_NAMES>.
 
+B<KTLS>: Enables kernel TLS if support has been compiled in, and it is supported
+by the negotiated ciphersuites and extensions. Equivalent to
+B<SSL_OP_ENABLE_KTLS>.
+
 =item B<VerifyMode>
 
 The B<value> argument is a comma separated list of flags to set.

diff --git a/doc/man3/SSL_CTX_set_mode.pod b/doc/man3/SSL_CTX_set_mode.pod
index a814022d3cbb9e3c717ce2655cdda4947d66d7ae..39b5e1906faab8fc32193eaf5bb496d0b67ca784 100644 (file)
--- a/doc/man3/SSL_CTX_set_mode.pod
+++ b/doc/man3/SSL_CTX_set_mode.pod
@@ -105,22 +105,6 @@ Enable asynchronous processing. TLS I/O operations may indicate a retry with
 SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is
 used to perform cryptographic operations. See L<SSL_get_error(3)>.
 
-=item SSL_MODE_NO_KTLS_TX
-
-Disable the use of the kernel TLS egress data-path.
-By default kernel TLS is enabled if it is supported by the negotiated ciphersuites
-and extensions and OpenSSL has been compiled with support for it.
-The kernel TLS data-path implements the record layer,
-and the crypto algorithm. The kernel will utilize the best hardware
-available for crypto. Using the kernel data-path should reduce the memory
-footprint of OpenSSL because no buffering is required. Also, the throughput
-should improve because data copy is avoided when user data is encrypted into
-kernel memory instead of the usual encrypt than copy to kernel.
-
-Kernel TLS might not support all the features of OpenSSL. For instance,
-renegotiation, and setting the maximum fragment size is not possible as of
-Linux 4.20.
-
 =item SSL_MODE_DTLS_SCTP_LABEL_LENGTH_BUG
 
 Older versions of OpenSSL had a bug in the computation of the label length
@@ -150,7 +134,6 @@ L<SSL_write(3)>, L<SSL_get_error(3)>
 =head1 HISTORY
 
 SSL_MODE_ASYNC was added in OpenSSL 1.1.0.
-SSL_MODE_NO_KTLS_TX was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 

diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod
index 68a15524309686f32a54218112513f1d5de13b4b..2212e8aca3400f2af58759306c5f08faa156a7b2 100644 (file)
--- a/doc/man3/SSL_CTX_set_options.pod
+++ b/doc/man3/SSL_CTX_set_options.pod
@@ -279,6 +279,29 @@ responsible for cleansing all other buffers. Most notably, this
 applies to buffers passed to functions like L<SSL_read(3)>,
 L<SSL_peek(3)> but also like L<SSL_write(3)>.
 
+=item SSL_OP_ENABLE_KTLS
+
+Enable the use of kernel TLS. In order to benefit from kernel TLS OpenSSL must
+have been compiled with support for it, and it must be supported by the
+negotiated ciphersuites and extensions. The specific ciphersuites and extensions
+that are supported may vary by platform and kernel version.
+
+The kernel TLS data-path implements the record layer, and the encryption
+algorithm. The kernel will utilize the best hardware
+available for encryption. Using the kernel data-path should reduce the memory
+footprint of OpenSSL because no buffering is required. Also, the throughput
+should improve because data copy is avoided when user data is encrypted into
+kernel memory instead of the usual encrypt then copy to kernel.
+
+Kernel TLS might not support all the features of OpenSSL. For instance,
+renegotiation, and setting the maximum fragment size is not possible as of
+Linux 4.20.
+
+Note that with kernel TLS enabled some cryptographic operations are performed
+by the kernel directly and not via any available OpenSSL Providers. This might
+be undesirable if, for example, the application requires all cryptographic
+operations to be performed by the FIPS provider.
+
 =back
 
 The following options no longer have any effect but their identifiers are