Only SHA3/SHAKE Init Updates via FIPS202 API layer

[manastasova]

Issues:

Resolves (some of) #CryptoAlg-2810

Description of changes:

AWS-LC supports SHA3 and SHAKE algorithms though low level SHA3_Init, SHA3_Update, SHA3_Final and SHAKE_init, SHAKE_Final APIs. Currently, there are two issues with the implementation and usage of SHA3 and SHAKE:

• There is no support for SHAKE_Update function. SHAKE is implemented by calling SHAKE_Init, SHA3_Update and SHAKE_Final.
• SHAKE_Final allows multiple consecutive calls to enable incremental XOF output generation.

This PR introduces the APIs that need changes in the function parameter list. Particularly, SHA3_Init used a parameter |pad_char|, which was used for differentiating SHA3_Init from SHAKE_Init functions.

This PR introduces only the changes in the Init functions (FIPS202_Init, FIPS202_Reset, SHA3_Init, and SHAKE_Init):

• Introduce (partially) new API layers - FIPS202, SHA3 and SHAKE.
  • Keccak1600 layer (Keccak1600_Squeeze/Absorb Layer (rename) #2097) implements KeccakF1600 Absorb and Squeeze functions; Keccak1600 layer does not manage internal input/output buffers.
  • FIPS202 layer implements (so far) Reset and Init functions. (Update and Finalize functionalities are to be introduced in following PRs); FIPS202 layer manages the internal input/output buffers, allowing incremental requests (not necessarily multiple of block size) to Update (Absorb) and Squeeze for input/output processing. (Other functionalities, such as zero-ing of bitstate, block size checks, etc. are also handled by FIPS202 API layer).
    • FIPS202 layer implements (so far) Reset and Init common behavior between SHA3 and SHAKE algorithms.
    • FIPS202 layer checks/updates the |ctx->padded| flag when handling a common behavior between SHA3 and SHAKE algorithms.
  • SHA3 layer implements (so far) Init functionality (Update, and Final are to be introduced in following PRs);
  • SHAKE layer implements XOF SHAKE algorithm, therefore, offers (so far) Init functionality (Absorb, Squeeze, and Final functionalities are to be introduced in following PRs);

Call-outs:

All SHA3_Init calls are updated:

• digests.c
• sha3_test.cc

Testing:

./crypto/crypto_test --gtest_filter="KeccakInternalTest.*"
./crypto/crypto_test --gtest_filter="SHA3Test.*"
./crypto/crypto_test --gtest_filter="SHAKETest.*"

./crypto/crypto_test --gtest_filter="All/PerKEMTest.*"
./crypto/crypto_test --gtest_filter="All/PQDSAParameterTest.*"

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 91.17647% with 3 lines in your changes missing coverage. Please review.

Project coverage is 78.95%. Comparing base (29be983) to head (f45f3d3).

Files with missing lines	Patch %	Lines
crypto/fipsmodule/sha/sha3.c	90.00%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2101   +/-   ##
=======================================
  Coverage   78.95%   78.95%           
=======================================
  Files         610      610           
  Lines      105293   105302    +9     
  Branches    14911    14924   +13     
=======================================
+ Hits        83129    83138    +9     
- Misses      21511    21512    +1     
+ Partials      653      652    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[andrewhop]

Reading FIPS 202 section B.2 where it defines the sha and shake pad values, why are we using the q = 2 values? Should that be configurable in the future?

[manastasova]

The values for the padding are the same, however, they are 'interleaved' by 0's in case the message is shorter than the block. E.g. the pad for sha3 is 0x06 (added after the last byte of the input); the rest of the block size is set to zero, where the last byte of the block is set to 0x80. When the last byte (+1 byte) of the message (message of length block size - 1 bytes) and the last byte of the block coincide, the last byte becomes 0x06 ^ 0x80, which will be 0x86. When messages are shorter, more zero's are added in the middle of these values. However, the implementation covers all the cases using only the 0x06 and 0x1f pad, where all the rest is 0's and last block byte is 0x80.

[andrewhop]

Should this also zero out ctx->buf?

Suggested change

	memset(ctx->A, 0, sizeof(ctx->A));
	OPENSSL_memset(ctx->A, 0, sizeof(ctx->A));

[manastasova]

The buf is only accessible through the buf_load value. So, even if it is not zero'ed, it should not be an issue. Once that data is placed into the buffer, the buf_load is assigned the number of bytes that are 'useful' and accessible. When buf_load is 0, there is no useful data in the buffer.
However, I can zero it.