Add EVP_DigestSqueeze() API.

Fixes #7894

This allows SHAKE to squeeze multiple times with different output sizes.

The existing EVP_DigestFinalXOF() API has been left as a one shot
operation. A similar interface is used by another toolkit.

The low level SHA3_Squeeze() function needed to change slightly so
that it can handle multiple squeezes. This involves changing the
assembler code so that it passes a boolean to indicate whether
the Keccak function should be called on entry.
At the provider level, the squeeze is buffered, so that it only requests
a multiple of the blocksize when SHA3_Squeeze() is called. On the first
call the value is zero, on subsequent calls the value passed is 1.

This PR is derived from the excellent work done by @nmathewson in
https://github.com/openssl/openssl/pull/7921

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21511)

5 files changed, 119 insertions, 40 deletions

diff --git a/doc/man7/EVP_MD-BLAKE2.pod b/doc/man7/EVP_MD-BLAKE2.pod
index 205b0c59be..288a6dd735 100644
--- a/doc/man7/EVP_MD-BLAKE2.pod
+++ b/doc/man7/EVP_MD-BLAKE2.pod
@@ -25,6 +25,17 @@ Known names are "BLAKE2B-512" and "BLAKE2b512".
 
 =back
 
+=head2 Settable Parameters
+
+"BLAKE2B-512" supports the following EVP_MD_CTX_set_params() key
+described in  L<EVP_DigestInit(3)/PARAMETERS>.
+
+=over 4
+
+=item "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>) <unsigned integer>
+
+=back
+
 =head2 Gettable Parameters
 
 This implementation supports the common gettable parameters described
diff --git a/doc/man7/EVP_MD-SHAKE.pod b/doc/man7/EVP_MD-SHAKE.pod
index 8a31cd53a8..6f1fe9cae6 100644
--- a/doc/man7/EVP_MD-SHAKE.pod
+++ b/doc/man7/EVP_MD-SHAKE.pod
@@ -65,15 +65,28 @@ 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
+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.
+
 =back
 
+=head1 NOTES
+
+For SHAKE-128, to ensure the maximum security strength of 128 bits, the output
+length passed to EVP_DigestFinalXOF() should be at least 32.
+
+For SHAKE-256, to ensure the maximum security strength of 256 bits, the output
+length passed to EVP_DigestFinalXOF() should be at least 64.
+
 =head1 SEE ALSO
 
 L<EVP_MD_CTX_set_params(3)>, L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
 
 =head1 COPYRIGHT
 
-Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man7/img/digest.png b/doc/man7/img/digest.png
index 9f35deb5dc..8a9f78a26b 100644
--- a/doc/man7/img/digest.png
+++ b/doc/man7/img/digest.png
diff --git a/doc/man7/life_cycle-digest.pod b/doc/man7/life_cycle-digest.pod
index 709fd0d04c..672e61c7e4 100644
--- a/doc/man7/life_cycle-digest.pod
+++ b/doc/man7/life_cycle-digest.pod
@@ -32,6 +32,14 @@ additional input or generating output.
 =item finaled
 
 This state represents the MD when it has generated output.
+For an XOF digest, this state represents the MD when it has generated a
+single-shot output.
+
+=item squeezed
+
+For an XOF digest, this state represents the MD when it has generated output.
+It can be called multiple times to generate more output. The output length is
+variable for each call.
 
 =item freed
 
@@ -46,39 +54,57 @@ The usual life-cycle of a MD is illustrated:
 
 =begin man
 
-                     +-------------------+
-                     |       start       |
-                     +-------------------+
-                       |
-                       | EVP_MD_CTX_new
-                       v
-                     +-------------------+         EVP_MD_CTX_reset
-                     |       newed       | <------------------------------+
-                     +-------------------+                                |
-                       |                                                  |
-                       | EVP_DigestInit                                   |
-                       v                                                  |
-                     +-------------------+                                |
-                +--> |    initialised    | <+ EVP_DigestInit              |
-                |    +-------------------+  |                             |
-                |      |                    |      EVP_DigestUpdate       |
-                |      | EVP_DigestUpdate   |    +------------------+     |
-                |      v                    |    v                  |     |
-                |    +------------------------------------------------+   |
- EVP_DigestInit |    |                    updated                     | --+
-                |    +------------------------------------------------+   |
-                |      |                    |                             |
-                |      | EVP_DigestFinal    | EVP_DigestFinalXOF          |
-                |      v                    v                             |
-                |    +------------------------------------------------+   |
-                +--- |                    finaled                     | --+
-                     +------------------------------------------------+
-                       |
-                       | EVP_MD_CTX_free
-                       v
-                     +-------------------+
-                     |       freed       |
-                     +-------------------+
+                                  +--------------------+
+                                  |       start        |
+                                  +--------------------+
+                                    |                            EVP_MD_CTX_reset
+                                    | EVP_MD_CTX_new           +-------------------------------------------------+
+                                    v                          v                                                 |
+              EVP_MD_CTX_reset    + - - - - - - - - - - - - - - - - - - - - - - +    EVP_MD_CTX_reset            |
+            +-------------------> '                   newed                     ' <--------------------+         |
+            |                     + - - - - - - - - - - - - - - - - - - - - - - +                      |         |
+            |                       |                                                                  |         |
+            |                       | EVP_DigestInit                                                   |         |
+            |                       v                                                                  |         |
+            |   EVP_DigestInit    + - - - - - - - - - - - - - - - - - - - - - - +                      |         |
+       +----+-------------------> '                initialised                  ' <+  EVP_DigestInit   |         |
+       |    |                     + - - - - - - - - - - - - - - - - - - - - - - +  |                   |         |
+       |    |                       |                     ^                        |                   |         |
+       |    |                       | EVP_DigestUpdate    | EVP_DigestInit         |                   |         |
+       |    |                       v                     |                        |                   |         |
+       |    |                     +---------------------------------------------+  |                   |         |
+       |    +-------------------- |                                             |  |                   |         |
+       |                          |                                             |  |                   |         |
+       |      EVP_DigestUpdate    |                                             |  |                   |         |
+       |    +-------------------- |                                             |  |                   |         |
+       |    |                     |                   updated                   |  |                   |         |
+       |    +-------------------> |                                             |  |                   |         |
+       |                          |                                             |  |                   |         |
+       |                          |                                             |  |                   |         |
+  +----+------------------------- |                                             | -+-------------------+----+    |
+  |    |                          +---------------------------------------------+  |                   |    |    |
+  |    |                            |                                              |                   |    |    |
+  |    |                            | EVP_DigestSqueeze        +-------------------+                   |    |    |
+  |    |                            v                          |                                       |    |    |
+  |    |      EVP_DigestSqueeze   +---------------------------------------------+                      |    |    |
+  |    |    +-------------------- |                                             |                      |    |    |
+  |    |    |                     |                  squeezed                   |                      |    |    |
+  |    |    +-------------------> |                                             | ---------------------+    |    |
+  |    |                          +---------------------------------------------+                           |    |
+  |    |                                                       |                                            |    |
+  |    |                                                       +---------------------------------------+    |    |
+  |    |                                                                                               |    |    |
+  |    |                          +---------------------------------------------+  EVP_DigestFinalXOF  |    |    |
+  |    +------------------------- |             finaled                         | <--------------------+----+    |
+  |                               +---------------------------------------------+                      |         |
+  |   EVP_DigestFinal               ^                     |    |                                       |         |
+  +---------------------------------+                     |    | EVP_MD_CTX_free                       |         |
+                                                          |    v                                       |         |
+                                                          |  +------------------+  EVP_MD_CTX_free     |         |
+                                                          |  |      freed       | <--------------------+         |
+                                                          |  +------------------+                                |
+                                                          |                                                      |
+                                                          +------------------------------------------------------+
 
 =end man
 
@@ -91,19 +117,21 @@ This is the canonical list.
 
 =begin man
 
- Function Call                --------------------- Current State ----------------------
-                              start   newed    initialised   updated     finaled   freed
+ Function Call                --------------------- Current State -----------------------------------
+                              start   newed    initialised   updated     finaled     squeezed   freed
  EVP_MD_CTX_new               newed
- EVP_DigestInit                    initialised initialised initialised initialised
+ EVP_DigestInit                    initialised initialised initialised initialised  initialised
  EVP_DigestUpdate                                updated     updated
  EVP_DigestFinal                                             finaled
  EVP_DigestFinalXOF                                          finaled
+ EVP_DigestSqueeze                                           squeezed                squeezed
  EVP_MD_CTX_free              freed   freed       freed       freed       freed
  EVP_MD_CTX_reset                     newed       newed       newed       newed
  EVP_MD_CTX_get_params                newed    initialised   updated
  EVP_MD_CTX_set_params                newed    initialised   updated
  EVP_MD_CTX_gettable_params           newed    initialised   updated
  EVP_MD_CTX_settable_params           newed    initialised   updated
+ EVP_MD_CTX_copy_ex                   newed    initialised   updated                 squeezed
 
 =end man
 
@@ -118,6 +146,7 @@ This is the canonical list.
     <th style="border:1px solid" align="center">initialised</th>
     <th style="border:1px solid" align="center">updated</th>
     <th style="border:1px solid" align="center">finaled</th>
+    <th style="border:1px solid" align="center">squeezed</th>
     <th style="border:1px solid" align="center">freed</th></tr>
 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_new</th>
     <td style="border:1px solid" align="center">newed</td>
@@ -125,6 +154,7 @@ This is the canonical list.
     <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_DigestInit</th>
     <td style="border:1px solid" align="center"></td>
@@ -132,6 +162,7 @@ This is the canonical list.
     <td style="border:1px solid" align="center">initialised</td>
     <td style="border:1px solid" align="center">initialised</td>
     <td style="border:1px solid" align="center">initialised</td>
+    <td style="border:1px solid" align="center">initialised</td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_DigestUpdate</th>
     <td style="border:1px solid" align="center"></td>
@@ -139,6 +170,7 @@ This is the canonical list.
     <td style="border:1px solid" align="center">updated</td>
     <td style="border:1px solid" align="center">updated</td>
     <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_DigestFinal</th>
     <td style="border:1px solid" align="center"></td>
@@ -146,6 +178,15 @@ This is the canonical list.
     <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center">finaled</td>
     <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_DigestSqueeze</th>
+    <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center">squeezed</td>
+    <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center">squeezed</td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_DigestFinalXOF</th>
     <td style="border:1px solid" align="center"></td>
@@ -153,6 +194,7 @@ This is the canonical list.
     <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center">finaled</td>
     <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_free</th>
     <td style="border:1px solid" align="center">freed</td>
@@ -160,6 +202,7 @@ This is the canonical list.
     <td style="border:1px solid" align="center">freed</td>
     <td style="border:1px solid" align="center">freed</td>
     <td style="border:1px solid" align="center">freed</td>
+    <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_reset</th>
     <td style="border:1px solid" align="center"></td>
@@ -167,6 +210,7 @@ This is the canonical list.
     <td style="border:1px solid" align="center">newed</td>
     <td style="border:1px solid" align="center">newed</td>
     <td style="border:1px solid" align="center">newed</td>
+    <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_get_params</th>
     <td style="border:1px solid" align="center"></td>
@@ -174,6 +218,7 @@ This is the canonical list.
     <td style="border:1px solid" align="center">initialised</td>
     <td style="border:1px solid" align="center">updated</td>
     <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_set_params</th>
     <td style="border:1px solid" align="center"></td>
@@ -181,6 +226,7 @@ This is the canonical list.
     <td style="border:1px solid" align="center">initialised</td>
     <td style="border:1px solid" align="center">updated</td>
     <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_gettable_params</th>
     <td style="border:1px solid" align="center"></td>
@@ -188,6 +234,7 @@ This is the canonical list.
     <td style="border:1px solid" align="center">initialised</td>
     <td style="border:1px solid" align="center">updated</td>
     <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
     <td style="border:1px solid" align="center"></td></tr>
 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_settable_params</th>
     <td style="border:1px solid" align="center"></td>
@@ -195,6 +242,15 @@ This is the canonical list.
     <td style="border:1px solid" align="center">initialised</td>
     <td style="border:1px solid" align="center">updated</td>
     <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center"></td></tr>
+<tr><th style="border:1px solid" align="left">EVP_MD_CTX_copy_ex</th>
+    <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center">newed</td>
+    <td style="border:1px solid" align="center">initialised</td>
+    <td style="border:1px solid" align="center">updated</td>
+    <td style="border:1px solid" align="center"></td>
+    <td style="border:1px solid" align="center">squeezed</td>
     <td style="border:1px solid" align="center"></td></tr>
 </table>
 
@@ -211,7 +267,7 @@ L<provider-digest(7)>, L<EVP_DigestInit(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod
index 2c99b8b3fb..d23da59e1a 100644
--- a/doc/man7/provider-digest.pod
+++ b/doc/man7/provider-digest.pod
@@ -198,8 +198,7 @@ This digest method can only handle one block of input.
 
 =item B<EVP_MD_FLAG_XOF>
 
-This digest method is an extensible-output function (XOF) and supports
-setting the B<OSSL_DIGEST_PARAM_XOFLEN> parameter.
+This digest method is an extensible-output function (XOF).
 
 =item B<EVP_MD_FLAG_DIGALGID_NULL>