From f24da0ea9cc7bbdaee1ac63f6d66d827c5b97346 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Wed, 20 Dec 2023 10:07:39 +0000 Subject: [PATCH] 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. --- doc/man1/openssl-s_client.pod.in | 6 +++++- doc/man1/openssl-s_server.pod.in | 8 ++++++-- doc/man3/COMP_CTX_new.pod | 3 ++- doc/man3/SSL_CONF_cmd.pod | 5 ++++- doc/man3/SSL_CTX_set_options.pod | 8 ++++++-- 5 files changed, 23 insertions(+), 7 deletions(-) diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index f8db2658be27cd..032edb2a368f86 100644 --- 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 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 9726a5c871f4a4..6b9c91ba87eccc 100644 --- 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 for +more information. =item B<-no_ticket> diff --git a/doc/man3/COMP_CTX_new.pod b/doc/man3/COMP_CTX_new.pod index f73df521e8d615..997f1187f46be9 100644 --- a/doc/man3/COMP_CTX_new.pod +++ b/doc/man3/COMP_CTX_new.pod @@ -123,7 +123,8 @@ Zstandard may be found at L. Compression of SSL/TLS records is not recommended, as it has been shown to lead to the CRIME attack L. It is disabled by default, and may be enabled by clearing the -SSL_OP_NO_COMPRESSION options of the L or +SSL_OP_NO_COMPRESSION option and setting the security level as appropriate. +See the documentation for the L and L 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 54ab886af10c87..5dc468dc2e84b2 100644 --- 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. 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. =item B<-no_ticket> diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod index 272b2a93e4f6af..9d24f71f6df2ca 100644 --- 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 this option will +have no effect without also changing the default security level. See +L. =item SSL_OP_NO_ENCRYPT_THEN_MAC