SHAKE documentation updates for default output length.

Fixes #18586

In order to not break existing applications the OpenSSL documentation
related to SHAKE has been updated.

Background:

All digests algorithms (including XOF's) use the bitlen as the default output length.
This results in a security strength of bitlen / 2.

This means that SHAKE128 will by default have an output length of 16
bytes and a security strength of 64 bits.

For SHAKE256 the default output length is 32 bytes and has a security
strength of 128 bits.

This behaviour was present in 1.1.1 and has been duplicated in the
provider SHAKE algorithms for 3.0.

The SHAKE XOF algorithms have a security strength of
min(bitlen, output xof length in bits / 2).

Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/18622)

1 files changed, 6 insertions, 1 deletions

diff --git a/apps/dgst.c b/apps/dgst.c
index f009df8093..b6363eb534 100644
--- a/apps/dgst.c
+++ b/apps/dgst.c
@@ -66,7 +66,7 @@ const OPTIONS dgst_options[] = {
     {"keyform", OPT_KEYFORM, 'f', "Key file format (ENGINE, other values ignored)"},
     {"hex", OPT_HEX, '-', "Print as hex dump"},
     {"binary", OPT_BINARY, '-', "Print in binary form"},
-    {"xoflen", OPT_XOFLEN, 'p', "Output length for XOF algorithms"},
+    {"xoflen", OPT_XOFLEN, 'p', "Output length for XOF algorithms. To obtain the maximum security strength set this to 32 (or greater) for SHAKE128, and 64 (or greater) for SHAKE256"},
     {"d", OPT_DEBUG, '-', "Print debug info"},
     {"debug", OPT_DEBUG, '-', "Print debug info"},
 
@@ -419,6 +419,11 @@ int dgst_main(int argc, char **argv)
             BIO_printf(bio_err, "Length can only be specified for XOF\n");
             goto end;
         }
+        /*
+         * Signing using XOF is not supported by any algorithms currently since
+         * each algorithm only calls EVP_DigestFinal_ex() in their sign_final
+         * and verify_final methods.
+         */
         if (sigkey != NULL) {
             BIO_printf(bio_err, "Signing key cannot be specified for XOF\n");
             goto end;