add _ctx_release() functions to support 3rd party FIPS202 implementat…

…ions using dynamically allocated state

Some consumers may want to provide their own Kecak implementations
instead of using the ones provided by us. Such implementations
may be using Keccak implementations using dynamic memory allocations,
e.g., the Keccak from OpenSSL does that.
In that case, we need to explicitly free the state once it is
no longer needed.

This PR adds corresponding functions called _ctx_release() and calls
them in the appropriate places.
Since all of our Keccak implementations use a statically allocated state,
the xxx_ctx_release() is implemented as a no-op here.

Naming of functions follows PQClean and liboqs.

Signed-off-by: Matthias J. Kannwischer <[email protected]>

fips202/fips202.c

@@ -210,6 +210,8 @@ void shake256_inc_squeeze(uint8_t *output, size_t outlen,
   keccak_inc_squeeze(output, outlen, state->ctx, SHAKE256_RATE);
 }
 
+void shake256_inc_ctx_release(shake256incctx *state) { (void)state; }
+
 /*************************************************
  * Name:        shake128_absorb
  *
@@ -248,6 +250,9 @@ void shake128_squeezeblocks(uint8_t *output, size_t nblocks,
   keccak_squeezeblocks(output, nblocks, state->ctx, SHAKE128_RATE);
 }
 
+
+void shake128_ctx_release(shake128ctx *state) { (void)state; }
+
 /*************************************************
  * Name:        shake256
  *

fips202/fips202.h

@@ -14,10 +14,6 @@
 #define SHA3_384_RATE 104
 #define SHA3_512_RATE 72
 
-// Context for incremental API
-typedef struct {
-  uint64_t ctx[26];
-} shake128incctx;
 
 // Context for non-incremental API
 typedef struct {
@@ -29,11 +25,6 @@ typedef struct {
   uint64_t ctx[26];
 } shake256incctx;
 
-// Context for non-incremental API
-typedef struct {
-  uint64_t ctx[25];
-} shake256ctx;
-
 /* Initialize the state and absorb the provided input.
  *
  * This function does not support being called multiple times
@@ -58,6 +49,11 @@ REQUIRES(IS_FRESH(output, nblocks *SHAKE128_RATE))
 ASSIGNS(OBJECT_WHOLE(output), OBJECT_WHOLE(state));
 // clang-format on
 
+
+/* Free the state */
+#define shake128_ctx_release FIPS202_NAMESPACE(shake128_ctx_release)
+void shake128_ctx_release(shake128ctx *state);
+
 /* Initialize incremental hashing API */
 #define shake256_inc_init FIPS202_NAMESPACE(shake256_inc_init)
 void shake256_inc_init(shake256incctx *state);
@@ -76,6 +72,10 @@ void shake256_inc_finalize(shake256incctx *state);
 void shake256_inc_squeeze(uint8_t *output, size_t outlen,
                           shake256incctx *state);
 
+/* Free the state */
+#define shake256_inc_ctx_release FIPS202_NAMESPACE(shake256_inc_ctx_release)
+void shake256_inc_ctx_release(shake256incctx *state);
+
 /* One-stop SHAKE256 call */
 #define shake256 FIPS202_NAMESPACE(shake256)
 void shake256(uint8_t *output, size_t outlen, const uint8_t *input,
@@ -93,4 +93,5 @@ void sha3_256(uint8_t *output, const uint8_t *input, size_t inlen);
 /* One-stop SHA3-512 shop */
 #define sha3_512 FIPS202_NAMESPACE(sha3_512)
 void sha3_512(uint8_t *output, const uint8_t *input, size_t inlen);
+
 #endif

fips202/fips202x4.c

@@ -81,6 +81,10 @@ void shake256x4_squeezeblocks(uint8_t *out0, uint8_t *out1, uint8_t *out2,
                           SHAKE256_RATE);
 }
 
+void shake128x4_ctx_release(keccakx4_state *state) { (void)state; }
+
+void shake256x4_ctx_release(keccakx4_state *state) { (void)state; }
+
 void shake256x4(uint8_t *out0, uint8_t *out1, uint8_t *out2, uint8_t *out3,
                 size_t outlen, uint8_t *in0, uint8_t *in1, uint8_t *in2,
                 uint8_t *in3, size_t inlen) {

fips202/fips202x4.h

@@ -29,6 +29,12 @@ void shake256x4_squeezeblocks(uint8_t *out0, uint8_t *out1, uint8_t *out2,
                               uint8_t *out3, size_t nblocks,
                               keccakx4_state *state);
 
+#define shake128x4_ctx_release FIPS202_NAMESPACE(shake128x4_ctx_release)
+void shake128x4_ctx_release(keccakx4_state *state);
+
+#define shake256x4_ctx_release FIPS202_NAMESPACE(shake256x4_ctx_release)
+void shake256x4_ctx_release(keccakx4_state *state);
+
 #define shake256x4 FIPS202_NAMESPACE(shake256x4)
 void shake256x4(uint8_t *out0, uint8_t *out1, uint8_t *out2, uint8_t *out3,
                 size_t outlen, uint8_t *in0, uint8_t *in1, uint8_t *in2,

mlkem/indcpa.c

@@ -179,6 +179,7 @@ static void gen_matrix_entry_x4(poly *vec[4],
       ctr[j] = rej_uniform(vec[j]->coeffs, MLKEM_N, ctr[j], bufx[j], buflen);
     }
   }
+  shake128x4_ctx_release(&statex);
 }
 
 // Generate a single A matrix entry from a seed, using rejection
@@ -215,6 +216,8 @@ void gen_matrix_entry(poly *entry,
       shake128_squeezeblocks(buf, 1, &state);
       ctr = rej_uniform(entry->coeffs, MLKEM_N, ctr, buf, SHAKE128_RATE);
     }
+
+  shake128_ctx_release(&state);
 }
 
 /*************************************************

mlkem/symmetric-shake.c

@@ -50,4 +50,5 @@ void mlkem_shake256_rkprf(uint8_t out[MLKEM_SSBYTES],
   shake256_inc_absorb(&s, input, MLKEM_CIPHERTEXTBYTES);
   shake256_inc_finalize(&s);
   shake256_inc_squeeze(out, MLKEM_SSBYTES, &s);
+  shake256_inc_ctx_release(&s);
 }

test/gen_KAT.c

@@ -61,5 +61,7 @@ int main(void) {
     print_hex("ss", ss1, sizeof(ss1));
   }
 
+  shake256_inc_ctx_release(&state);
+
   return 0;
 }