From: Tomas Mraz <tomas@openssl.org>
Date: Wed, 24 Apr 2024 16:42:39 +0000 (+0200)
Subject: Document that SHAKE-128 and SHAKE-256 have no default digest length
X-Git-Tag: openssl-3.4.0-alpha1~547
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ad3f28c5fbd5dcbc763a650313fd666b0e339cca;p=thirdparty%2Fopenssl.git

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 cf0efe31ba5..5615e48a1fc 100644
--- 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 8389539bd87..10aa3de3dc3 100644
--- 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.