Improve the documentation on TLS record compression

TLS record compression is off by default. Even if you switch it on, it
cannot be used at security level 2 which is the default in OpenSSL 3.2 and
above. Update the docs to point this out.

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Kurt Roeckx <kurt@roeckx.be>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23104)

diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in
index f8db2658be27cd63462b387299e64d41fb81cf0b..032edb2a368f862b72eb51752038ace3f5920ec1 100644 (file)
--- a/doc/man1/openssl-s_client.pod.in
+++ b/doc/man1/openssl-s_client.pod.in
@@ -630,7 +630,11 @@ Disables support for receiving TLSv1.3 compressed certificate.
 Enables support for SSL/TLS compression.
 This option was introduced in OpenSSL 1.1.0.
 TLS compression is not recommended and is off by default as of
-OpenSSL 1.1.0.
+OpenSSL 1.1.0. TLS compression can only be used in security level 1 or
+lower. From OpenSSL 3.2.0 and above the default security level is 2, so this
+option will have no effect without also changing the security level. Use the
+B<-cipher> option to change the security level. See L<openssl-ciphers(1)> for
+more information.
 
 =item B<-no_comp>
 

diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in
index 9726a5c871f4a4f2f010304532e1169ad9473e0b..6b9c91ba87ecccd95662f62e9916ccce3b4107d9 100644 (file)
--- a/doc/man1/openssl-s_server.pod.in
+++ b/doc/man1/openssl-s_server.pod.in
@@ -627,10 +627,14 @@ OpenSSL 1.1.0.
 
 =item B<-comp>
 
-Enable negotiation of TLS compression.
+Enables support for SSL/TLS compression.
 This option was introduced in OpenSSL 1.1.0.
 TLS compression is not recommended and is off by default as of
-OpenSSL 1.1.0.
+OpenSSL 1.1.0. TLS compression can only be used in security level 1 or
+lower. From OpenSSL 3.2.0 and above the default security level is 2, so this
+option will have no effect without also changing the security level. Use the
+B<-cipher> option to change the security level. See L<openssl-ciphers(1)> for
+more information.
 
 =item B<-no_ticket>
 

diff --git a/doc/man3/COMP_CTX_new.pod b/doc/man3/COMP_CTX_new.pod
index f73df521e8d61563e4dcaa8d9435748dbfde9367..997f1187f46be916ef87249cfcbd9a4cffed3bcb 100644 (file)
--- a/doc/man3/COMP_CTX_new.pod
+++ b/doc/man3/COMP_CTX_new.pod
@@ -123,7 +123,8 @@ Zstandard may be found at L<https://github.com/facebook/zstd>.
 Compression of SSL/TLS records is not recommended, as it has been
 shown to lead to the CRIME attack L<https://en.wikipedia.org/wiki/CRIME>.
 It is disabled by default, and may be enabled by clearing the
-SSL_OP_NO_COMPRESSION options of the L<SSL_CTX_set_options(3)> or
+SSL_OP_NO_COMPRESSION option and setting the security level as appropriate.
+See the documentation for the L<SSL_CTX_set_options(3)> and
 L<SSL_set_options(3)> functions.
 
 Compression is also used to support certificate compression as described

diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod
index 54ab886af10c878b22b2039f2565b47d3fd4f031..5dc468dc2e84b2f70a3359cadfcdbe2fa6ee63a2 100644 (file)
--- a/doc/man3/SSL_CONF_cmd.pod
+++ b/doc/man3/SSL_CONF_cmd.pod
@@ -46,7 +46,10 @@ As of OpenSSL 1.1.0, compression is off by default.
 Enables support for SSL/TLS compression, same as clearing
 B<SSL_OP_NO_COMPRESSION>.
 This command was introduced in OpenSSL 1.1.0.
-As of OpenSSL 1.1.0, compression is off by default.
+As of OpenSSL 1.1.0, compression is off by default. TLS compression can only be
+used in security level 1 or lower. From OpenSSL 3.2.0 and above the default
+security level is 2, so this option will have no effect without also changing
+the security level. See L<SSL_CTX_set_security_level(3)>.
 
 =item B<-no_ticket>
 

diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod
index 272b2a93e4f6affe8983e410bd999fb03f0e91c6..28b5d680f51c2250882565dfe183ce2d816bead1 100644 (file)
--- a/doc/man3/SSL_CTX_set_options.pod
+++ b/doc/man3/SSL_CTX_set_options.pod
@@ -256,8 +256,12 @@ and compressed certificates will not be accepted from the peer.
 
 =item SSL_OP_NO_COMPRESSION
 
-Do not use compression even if it is supported. This option is set by default.
-To switch it off use SSL_clear_options().
+Do not use TLS record compression even if it is supported. This option is set by
+default. To switch it off use SSL_clear_options(). Note that TLS record
+compression is not recommended and is not available at security level 2 or
+above. From OpenSSL 3.2 the default security level is 2, so clearing this option
+will have no effect without also changing the default security level. See
+L<SSL_CTX_set_security_level(3)>.
 
 =item SSL_OP_NO_ENCRYPT_THEN_MAC