SHA3 and SHAKE - New API Design

crypto/fipsmodule/digest/digests.c

@@ -326,7 +326,7 @@ DEFINE_METHOD_FUNCTION(EVP_MD, EVP_sha512_256) {
 
 
 static void sha3_224_init(EVP_MD_CTX *ctx) {
-  CHECK(SHA3_Init(ctx->md_data, SHA3_PAD_CHAR, SHA3_224_DIGEST_BITLENGTH));
+  CHECK(SHA3_Init(ctx->md_data, SHA3_224_DIGEST_BITLENGTH));
 }
 
 static void sha3_224_update(EVP_MD_CTX *ctx, const void *data, size_t count) {
@@ -351,7 +351,7 @@ DEFINE_METHOD_FUNCTION(EVP_MD, EVP_sha3_224) {
 
 
 static void sha3_256_init(EVP_MD_CTX *ctx) {
-  CHECK(SHA3_Init(ctx->md_data, SHA3_PAD_CHAR, SHA3_256_DIGEST_BITLENGTH));
+  CHECK(SHA3_Init(ctx->md_data, SHA3_256_DIGEST_BITLENGTH));
 }
 
 static void sha3_256_update(EVP_MD_CTX *ctx, const void *data, size_t count) {
@@ -376,7 +376,7 @@ DEFINE_METHOD_FUNCTION(EVP_MD, EVP_sha3_256) {
 
 
 static void sha3_384_init(EVP_MD_CTX *ctx) {
-  CHECK(SHA3_Init(ctx->md_data, SHA3_PAD_CHAR, SHA3_384_DIGEST_BITLENGTH));
+  CHECK(SHA3_Init(ctx->md_data, SHA3_384_DIGEST_BITLENGTH));
 }
 
 static void sha3_384_update(EVP_MD_CTX *ctx, const void *data, size_t count) {
@@ -401,7 +401,7 @@ DEFINE_METHOD_FUNCTION(EVP_MD, EVP_sha3_384) {
 
 
 static void sha3_512_init(EVP_MD_CTX *ctx) {
-  CHECK(SHA3_Init(ctx->md_data, SHA3_PAD_CHAR, SHA3_512_DIGEST_BITLENGTH));
+  CHECK(SHA3_Init(ctx->md_data, SHA3_512_DIGEST_BITLENGTH));
 }
 
 static void sha3_512_update(EVP_MD_CTX *ctx, const void *data, size_t count) {
@@ -430,7 +430,7 @@ static void shake128_init(EVP_MD_CTX *ctx) {
 }
 
 static void shake128_update(EVP_MD_CTX *ctx, const void *data, size_t count) {
-  CHECK(SHA3_Update(ctx->md_data, data, count));
+  CHECK(SHAKE_Absorb(ctx->md_data, data, count));
 }
 
 static void shake128_final(EVP_MD_CTX *ctx, uint8_t *md, size_t len) {
@@ -455,7 +455,7 @@ static void shake256_init(EVP_MD_CTX *ctx) {
 }
 
 static void shake256_update(EVP_MD_CTX *ctx, const void *data, size_t count) {
-  CHECK(SHA3_Update(ctx->md_data, data, count));
+  CHECK(SHAKE_Absorb(ctx->md_data, data, count));
 }
 
 static void shake256_finalXOF(EVP_MD_CTX *ctx, uint8_t *md, size_t len) {

crypto/fipsmodule/ml_dsa/ml_dsa_ref/poly.c

@@ -316,9 +316,9 @@ void ml_dsa_poly_uniform(ml_dsa_poly *a,
   t[1] = nonce >> 8;
 
   SHAKE_Init(&state, SHAKE128_BLOCKSIZE);
-  SHA3_Update(&state, seed, ML_DSA_SEEDBYTES);
-  SHA3_Update(&state, t, 2);
-  SHAKE_Final(buf, &state, POLY_UNIFORM_NBLOCKS * SHAKE128_BLOCKSIZE);
+  SHAKE_Absorb(&state, seed, ML_DSA_SEEDBYTES);
+  SHAKE_Absorb(&state, t, 2);
+  SHAKE_Squeeze(buf, &state, POLY_UNIFORM_NBLOCKS * SHAKE128_BLOCKSIZE);
 
   ctr = ml_dsa_rej_uniform(a->coeffs, ML_DSA_N, buf, buflen);
 
@@ -327,7 +327,7 @@ void ml_dsa_poly_uniform(ml_dsa_poly *a,
     for(i = 0; i < off; ++i)
       buf[i] = buf[buflen - off + i];
 
-    SHAKE_Final(buf + off, &state, POLY_UNIFORM_NBLOCKS * SHAKE128_BLOCKSIZE);
+    SHAKE_Squeeze(buf + off, &state, POLY_UNIFORM_NBLOCKS * SHAKE128_BLOCKSIZE);
     buflen = SHAKE128_BLOCKSIZE + off;
     ctr += ml_dsa_rej_uniform(a->coeffs + ctr, ML_DSA_N - ctr, buf, buflen);
   }
@@ -418,16 +418,17 @@ void ml_dsa_poly_uniform_eta(ml_dsa_params *params,
   t[1] = nonce >> 8;
 
   SHAKE_Init(&state, SHAKE256_BLOCKSIZE);
-  SHA3_Update(&state, seed, ML_DSA_CRHBYTES);
-  SHA3_Update(&state, t, 2);
-  SHAKE_Final(buf, &state, ML_DSA_POLY_UNIFORM_ETA_NBLOCKS_MAX * SHAKE256_BLOCKSIZE);
+  SHAKE_Absorb(&state, seed, ML_DSA_CRHBYTES);
+  SHAKE_Absorb(&state, t, 2);
+  SHAKE_Squeeze(buf, &state, ML_DSA_POLY_UNIFORM_ETA_NBLOCKS_MAX * SHAKE256_BLOCKSIZE);
 
   ctr = rej_eta(params, a->coeffs, ML_DSA_N, buf, buflen);
 
   while(ctr < ML_DSA_N) {
-    SHAKE_Final(buf, &state, SHAKE256_BLOCKSIZE);
+    SHAKE_Squeeze(buf, &state, SHAKE256_BLOCKSIZE);
     ctr += rej_eta(params, a->coeffs + ctr, ML_DSA_N - ctr, buf, SHAKE256_BLOCKSIZE);
   }
+
   /* FIPS 204. Section 3.6.3 Destruction of intermediate values. */
   OPENSSL_cleanse(buf, sizeof(buf));
   OPENSSL_cleanse(&state, sizeof(state));
@@ -459,9 +460,8 @@ void ml_dsa_poly_uniform_gamma1(ml_dsa_params *params,
   t[1] = nonce >> 8;
 
   SHAKE_Init(&state, SHAKE256_BLOCKSIZE);
-  SHA3_Update(&state, seed, ML_DSA_CRHBYTES);
-  SHA3_Update(&state, t, 2);
-
+  SHAKE_Absorb(&state, seed, ML_DSA_CRHBYTES);
+  SHAKE_Absorb(&state, t, 2);
   SHAKE_Final(buf, &state, POLY_UNIFORM_GAMMA1_NBLOCKS * SHAKE256_BLOCKSIZE);
   ml_dsa_polyz_unpack(params, a, buf);
   /* FIPS 204. Section 3.6.3 Destruction of intermediate values. */
@@ -487,8 +487,8 @@ void ml_dsa_poly_challenge(ml_dsa_params *params, ml_dsa_poly *c, const uint8_t
   KECCAK1600_CTX state;
 
   SHAKE_Init(&state, SHAKE256_BLOCKSIZE);
-  SHA3_Update(&state, seed, params->c_tilde_bytes);
-  SHAKE_Final(buf, &state, SHAKE256_BLOCKSIZE);
+  SHAKE_Absorb(&state, seed, params->c_tilde_bytes);
+  SHAKE_Squeeze(buf, &state, SHAKE256_BLOCKSIZE);
 
   signs = 0;
   for(i = 0; i < 8; ++i) {
@@ -502,7 +502,7 @@ void ml_dsa_poly_challenge(ml_dsa_params *params, ml_dsa_poly *c, const uint8_t
   for(i = ML_DSA_N-params->tau; i < ML_DSA_N; ++i) {
     do {
       if(pos >= SHAKE256_BLOCKSIZE) {
-        SHAKE_Final(buf, &state, SHAKE256_BLOCKSIZE);
+        SHAKE_Squeeze(buf, &state, SHAKE256_BLOCKSIZE);
         pos = 0;
       }
 

crypto/fipsmodule/ml_dsa/ml_dsa_ref/sign.c

@@ -156,16 +156,16 @@ int ml_dsa_sign_internal(ml_dsa_params *params,
   // processing of M' in the external function. However, as M' = (pre, msg),
   // mu = CRH(tr, M') = CRH(tr, pre, msg).
   SHAKE_Init(&state, SHAKE256_BLOCKSIZE);
-  SHA3_Update(&state, tr, ML_DSA_TRBYTES);
-  SHA3_Update(&state, pre, prelen);
-  SHA3_Update(&state, m, mlen);
+  SHAKE_Absorb(&state, tr, ML_DSA_TRBYTES);
+  SHAKE_Absorb(&state, pre, prelen);
+  SHAKE_Absorb(&state, m, mlen);
   SHAKE_Final(mu, &state, ML_DSA_CRHBYTES);
 
   /* FIPS 204: line 7 Compute rhoprime = CRH(key, rnd, mu) */
   SHAKE_Init(&state, SHAKE256_BLOCKSIZE);
-  SHA3_Update(&state, key, ML_DSA_SEEDBYTES);
-  SHA3_Update(&state, rnd, ML_DSA_RNDBYTES);
-  SHA3_Update(&state, mu, ML_DSA_CRHBYTES);
+  SHAKE_Absorb(&state, key, ML_DSA_SEEDBYTES);
+  SHAKE_Absorb(&state, rnd, ML_DSA_RNDBYTES);
+  SHAKE_Absorb(&state, mu, ML_DSA_CRHBYTES);
   SHAKE_Final(rhoprime, &state, ML_DSA_CRHBYTES);
 
   /* FIPS 204: line 5 Expand matrix and transform vectors */
@@ -191,8 +191,8 @@ int ml_dsa_sign_internal(ml_dsa_params *params,
   ml_dsa_polyveck_pack_w1(params, sig, &w1);
 
   SHAKE_Init(&state, SHAKE256_BLOCKSIZE);
-  SHA3_Update(&state, mu, ML_DSA_CRHBYTES);
-  SHA3_Update(&state, sig, params->k * params->poly_w1_packed_bytes);
+  SHAKE_Absorb(&state, mu, ML_DSA_CRHBYTES);
+  SHAKE_Absorb(&state, sig, params->k * params->poly_w1_packed_bytes);
   SHAKE_Final(sig, &state, params->c_tilde_bytes);
   ml_dsa_poly_challenge(params, &cp, sig);
   ml_dsa_poly_ntt(&cp);
@@ -395,9 +395,9 @@ int ml_dsa_verify_internal(ml_dsa_params *params,
   // Like crypto_sign_signature_internal, the processing of M' is performed
   // here, as opposed to within the external function.
   SHAKE_Init(&state, SHAKE256_BLOCKSIZE);
-  SHA3_Update(&state, tr, ML_DSA_TRBYTES);
-  SHA3_Update(&state, pre, prelen);
-  SHA3_Update(&state, m, mlen);
+  SHAKE_Absorb(&state, tr, ML_DSA_TRBYTES);
+  SHAKE_Absorb(&state, pre, prelen);
+  SHAKE_Absorb(&state, m, mlen);
   SHAKE_Final(mu, &state, ML_DSA_CRHBYTES);
 
   /* FIPS 204: line 9 Matrix-vector multiplication; compute Az - c2^dt1 */
@@ -423,9 +423,10 @@ int ml_dsa_verify_internal(ml_dsa_params *params,
 
   /* FIPS 204: line 12 Call random oracle and verify challenge */
   SHAKE_Init(&state, SHAKE256_BLOCKSIZE);
-  SHA3_Update(&state, mu, ML_DSA_CRHBYTES);
-  SHA3_Update(&state, buf, params->k * params->poly_w1_packed_bytes);
+  SHAKE_Absorb(&state, mu, ML_DSA_CRHBYTES);
+  SHAKE_Absorb(&state, buf, params->k * params->poly_w1_packed_bytes);
   SHAKE_Final(c2, &state, params->c_tilde_bytes);
+
   for(i = 0; i < params->c_tilde_bytes; ++i) {
     if(c[i] != c2[i]) {
       return -1;

crypto/fipsmodule/ml_kem/ml_kem_ref/symmetric-shake.c

@@ -29,8 +29,8 @@ void kyber_shake128_absorb(KECCAK1600_CTX *ctx,
   // SHAKE_Init always returns 1 when called with correct block size value
   SHAKE_Init(ctx, SHAKE128_BLOCKSIZE);
 
-  // SHA3_Update always returns 1 on first call of sizeof(extseed) (34 bytes)
-  SHA3_Update(ctx, extseed, sizeof(extseed));
+  // SHAKE_Absorb always returns 1 on first call of sizeof(extseed) (34 bytes)
+  SHAKE_Absorb(ctx, extseed, sizeof(extseed));
 }
 
 /*************************************************
@@ -48,8 +48,8 @@ void kyber_shake128_absorb(KECCAK1600_CTX *ctx,
 void kyber_shake128_squeeze(KECCAK1600_CTX *ctx, uint8_t *out, int nblocks)
 {
   // Return code checks can be omitted
-  // SHAKE_Final always returns 1
-  SHAKE_Final(out, ctx, nblocks * SHAKE128_BLOCKSIZE);
+  // SHAKE_Squeeze always returns 1 when |ctx->padded| flag is cleared
+  SHAKE_Squeeze(out, ctx, nblocks * SHAKE128_BLOCKSIZE);
 }
 
 /*************************************************
@@ -94,12 +94,12 @@ void kyber_shake256_rkprf(ml_kem_params *params, uint8_t out[KYBER_SSBYTES], con
   // SHAKE_Init always returns 1 when called with correct block size value
   SHAKE_Init(&ctx, SHAKE256_BLOCKSIZE);
 
-  // SHA3_Update always returns 1 on first call of KYBER_SYMBYTES (32 bytes)
-  SHA3_Update(&ctx, key, KYBER_SYMBYTES);
+  // SHAKE_Absorb always returns 1 on first call of KYBER_SYMBYTES (32 bytes)
+  SHAKE_Absorb(&ctx, key, KYBER_SYMBYTES);
 
-  // SHA3_Update always returns 1 processing all data blocks that don't need pad
-  SHA3_Update(&ctx, input, params->ciphertext_bytes);
+  // SHAKE_Absorb always returns 1 processing all data blocks that don't need pad
+  SHAKE_Absorb(&ctx, input, params->ciphertext_bytes);
 
-  // SHAKE_Final always returns 1
+  // SHAKE_Squeeze always returns 1 when |ctx->padded| flag is cleared (no previous calls to SHAKE_Squeeze)
   SHAKE_Final(out, &ctx, KYBER_SSBYTES);
 }

crypto/fipsmodule/sha/internal.h

@@ -71,6 +71,14 @@ extern "C" {
 // SHAKE128 has the maximum block size among the SHA3/SHAKE algorithms.
 #define SHA3_MAX_BLOCKSIZE SHAKE128_BLOCKSIZE
 
+// Define state flag values for Keccak-based functions
+#define KECCAK1600_STATE_ABSORB     0 
+#define KECCAK1600_STATE_SQUEEZE    1  
+// KECCAK1600_STATE_FINAL restricts the incremental calls to SHAKE_Final .
+// KECCAK1600_STATE_FINAL can be called once. SHAKE_Squeeze cannot be called after SHAKE_Final.
+// SHAKE_Squeeze should be called for streaming XOF output.
+#define KECCAK1600_STATE_FINAL      2 
+
 typedef struct keccak_st KECCAK1600_CTX;
 
 // The data buffer should have at least the maximum number of
@@ -82,7 +90,7 @@ struct keccak_st {
   size_t buf_load;                                 // used bytes in below buffer
   uint8_t buf[SHA3_MAX_BLOCKSIZE];                 // should have at least the max data block size bytes
   uint8_t pad;                                     // padding character
-  uint8_t padded;                                  // denotes if padding has been performed
+  uint8_t state;                                  // denotes the keccak phase (absorb, squeeze, final)
 };
 
 // Define SHA{n}[_{variant}]_ASM if sha{n}_block_data_order[_{variant}] is
@@ -396,32 +404,39 @@ OPENSSL_EXPORT uint8_t *SHAKE128(const uint8_t *data, const size_t in_len,
 OPENSSL_EXPORT uint8_t *SHAKE256(const uint8_t *data, const size_t in_len,
                                  uint8_t *out, size_t out_len);
 
-// SHAKE_Init initializes |ctx| with specified |block_size|, returns 1 on
-// success and 0 on failure. Calls SHA3_Init under the hood.
-int SHAKE_Init(KECCAK1600_CTX *ctx, size_t block_size);
+// SHA3_Init initialises |ctx| fields and returns 1 on success and 0 on failure.
+OPENSSL_EXPORT int SHA3_Init(KECCAK1600_CTX *ctx, size_t bitlen);
 
-// SHAKE_Final writes |len| bytes of finalized digest to |md|, returns 1 on
-// success and 0 on failure. Calls SHA3_Final under the hood.
-int SHAKE_Final(uint8_t *md, KECCAK1600_CTX *ctx, size_t len);
+// SHA3_Update check |ctx| pointer and |len| value and calls FIPS202_Update.
+int SHA3_Update(KECCAK1600_CTX *ctx, const void *data,
+                               size_t len);
 
-// SHA3_Reset zeros the bitstate and the amount of processed input.
-void SHA3_Reset(KECCAK1600_CTX *ctx);
+// SHA3_Final pads the last data block and processes it through Keccak1600_Absorb.
+// It writes |md_digest| bytes of finalized digest to |md|, returns 1 on
+// success and 0 on failure.
+OPENSSL_EXPORT int SHA3_Final(uint8_t *md, KECCAK1600_CTX *ctx);
 
-// SHA3_Init initialises |ctx| fields and returns 1 on success and 0 on failure.
-OPENSSL_EXPORT int SHA3_Init(KECCAK1600_CTX *ctx, uint8_t pad, size_t bitlen);
+// SHAKE_Init initializes |ctx| with specified |block_size|, returns 1 on
+// success and 0 on failure. Calls SHA3_Init under the hood.
+OPENSSL_EXPORT int SHAKE_Init(KECCAK1600_CTX *ctx, size_t block_size);
+
+// SHAKE_Absorb checks |ctx| pointer and |len| values and calls FIPS202_Update.
+OPENSSL_EXPORT int SHAKE_Absorb(KECCAK1600_CTX *ctx, const void *data,
+                               size_t len);
 
-// SHA3_Update processes all data blocks that don't need pad through
-// |Keccak1600_Absorb| and returns 1 and 0 on failure.
-int SHA3_Update(KECCAK1600_CTX *ctx, const void *data, size_t len);
+// SHAKE_Final writes |len| bytes of finalized extendible output to |md|, returns 1 on
+// success and 0 on failure. It should be called once to finalize absorb and
+// initiate squeeze phase. Incremental XOF output should be generated via SHAKE_Squeeze.
+OPENSSL_EXPORT int SHAKE_Final(uint8_t *md, KECCAK1600_CTX *ctx, size_t len);
 
-// SHA3_Final pads the last data block and processes it through |Keccak1600_Absorb|.
-// It processes the data through |Keccak1600_Squeeze| and returns 1 and 0 on failure.
-int SHA3_Final(uint8_t *md, KECCAK1600_CTX *ctx);
+// SHAKE_Squeeze writes |len| bytes of incremental XOF output to |md|, returns 1 on
+// success and 0 on failure. It can be called multiple times.
+OPENSSL_EXPORT int SHAKE_Squeeze(uint8_t *md, KECCAK1600_CTX *ctx, size_t len);
 
 // Keccak1600_Absorb processes the largest multiple of |r| out of |len| bytes and
 // returns the remaining number of bytes.
-size_t Keccak1600_Absorb(uint64_t A[KECCAK1600_ROWS][KECCAK1600_ROWS],
-                         const uint8_t *data, size_t len, size_t r);
+OPENSSL_EXPORT size_t Keccak1600_Absorb(uint64_t A[KECCAK1600_ROWS][KECCAK1600_ROWS],
+                                  const uint8_t *data, size_t len, size_t r);
 
 // Keccak1600_Squeeze generates |out| value of |len| bytes (per call). It can be called
 // multiple times when used as eXtendable Output Function. |padded| indicates