From 6878f4300213cfd7d4f01e26a8b97f70344da100 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Wed, 7 Apr 2021 19:36:45 +0100 Subject: 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 (Merged from https://github.com/openssl/openssl/pull/14799) --- CHANGES.md | 6 ++++++ NEWS.md | 1 + doc/man3/SSL_CONF_cmd.pod | 4 ++++ doc/man3/SSL_CTX_set_mode.pod | 17 ----------------- doc/man3/SSL_CTX_set_options.pod | 23 +++++++++++++++++++++++ 5 files changed, 34 insertions(+), 17 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 581fda0c96..c85d106765 100644 --- 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 923a713087..c5811b9bde 100644 --- 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 97ebff047f..3fd1924de6 100644 --- a/doc/man3/SSL_CONF_cmd.pod +++ b/doc/man3/SSL_CONF_cmd.pod @@ -524,6 +524,10 @@ B: use CA names extension, enabled by default. Inverse of B: that is, B<-CANames> is the same as setting B. +B: Enables kernel TLS if support has been compiled in, and it is supported +by the negotiated ciphersuites and extensions. Equivalent to +B. + =item B The B 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 a814022d3c..39b5e1906f 100644 --- 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. -=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, L =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 68a1552430..2212e8aca3 100644 --- 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, L but also like L. +=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 -- cgit v1.2.3