Document that SHAKE-128 and SHAKE-256 have no default digest length

Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/24105)

diff --git a/CHANGES.md b/CHANGES.md
index cf0efe31ba54630b3aae41c64295f95d455196be..5615e48a1fcecdec45334dc919b34b7dd2ca15c5 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -41,6 +41,16 @@ OpenSSL 3.4
 
    *Tomáš Mráz*
 
+ * SHAKE-128 and SHAKE-256 implementations have no default digest length
+   anymore. That means these algorithms cannot be used with
+   EVP_DigestFinal/_ex() unless the `xoflen` param is set before.
+
+   This change was necessary because the preexisting default lengths were
+   half the size necessary for full collision resistance supported by these
+   algorithms.
+
+   *Tomáš Mráz*
+
  * Setting `config_diagnostics=1` in the config file will cause errors to
    be returned from SSL_CTX_new() and SSL_CTX_new_ex() if there is an error
    in the ssl module configuration.

diff --git a/doc/man7/EVP_MD-SHAKE.pod b/doc/man7/EVP_MD-SHAKE.pod
index 8389539bd8726911f1fa627c68ba6cc53f2ca0f4..10aa3de3dc36e5e17d924d8f8d36c926a6cb7fd6 100644 (file)
--- a/doc/man7/EVP_MD-SHAKE.pod
+++ b/doc/man7/EVP_MD-SHAKE.pod
@@ -62,15 +62,10 @@ settable for an B<EVP_MD_CTX> with L<EVP_MD_CTX_set_params(3)>:
 Sets the digest length for extendable output functions.
 The length of the "xoflen" parameter should not exceed that of a B<size_t>.
 
-For backwards compatibility reasons the default xoflen length for SHAKE-128 is
-16 (bytes) which results in a security strength of only 64 bits. To ensure the
-maximum security strength of 128 bits, the xoflen should be set to at least 32.
+The SHAKE-128 and SHAKE-256 implementations do not have any default digest
+length.
 
-For backwards compatibility reasons the default xoflen length for SHAKE-256 is
-32 (bytes) which results in a security strength of only 128 bits. To ensure the
-maximum security strength of 256 bits, the xoflen should be set to at least 64.
-
-This parameter may be used when calling either EVP_DigestFinal_ex() or
+This parameter must be set before calling either EVP_DigestFinal_ex() or
 EVP_DigestFinal(), since these functions were not designed to handle variable
 length output. It is recommended to either use EVP_DigestSqueeze() or
 EVP_DigestFinalXOF() instead.
@@ -89,6 +84,11 @@ length passed to EVP_DigestFinalXOF() should be at least 64.
 
 L<EVP_MD_CTX_set_params(3)>, L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
 
+=head1 HISTORY
+
+Since OpenSSL 3.4 the SHAKE-128 and SHAKE-256 implementations have no default
+digest length.
+
 =head1 COPYRIGHT
 
 Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.