Skip to content

Implement SHAKE in sha3.c #648

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
valeriosetti merged 14 commits into from
Jan 20, 2026
Merged

Implement SHAKE in sha3.c #648

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
0162e7d
Distinguish between "some sha3.c" and "some SHA3 hash"
gilles-peskine-arm Jan 9, 2026
19daa03
Temporarily declare built-in SHAKE in crypto_config.h
gilles-peskine-arm Jan 12, 2026
5ba3c76
Adding SHA-3 SHAKE128 and SHA-3 SHAKE256.
polhenarejos May 8, 2022
d7616d9
Allow multiple calls to mbedtls_sha3_finish()
polhenarejos May 20, 2022
b297452
Don't free the context in finish() when doing SHAKE
gilles-peskine-arm Oct 22, 2025
6f2a453
Add self tests for SHAKE
polhenarejos May 20, 2022
54f761e
Don't try to build and run SHAKE self-test when SHAKE is disabled
gilles-peskine-arm Oct 22, 2025
e6b87da
Update sha3.h documentation for SHAKE
gilles-peskine-arm Jan 8, 2026
c1deb33
SHAKE128, SHAKE256: multi-part input and multi-output tests
gilles-peskine-arm Jan 9, 2026
3988f04
Test SHA3/SHAKE with empty input, with or without an update() call
gilles-peskine-arm Jan 9, 2026
271168c
Add one-shot test cases for SHAKE128 and SHAKE256
gilles-peskine-arm Jan 9, 2026
239a07d
Fix build failure with some SHAKE but no SHA3 hash
gilles-peskine-arm Jan 12, 2026
2e0cbd8
Explain why MBEDTLS_SHA3_WANT_SHAKEnnn ≠ MBEDTLS_PSA_BUILTIN_SHAKEnnn
gilles-peskine-arm Jan 19, 2026
4c973cf
Simplify context reuse protection in mbedtls_sha3_starts
gilles-peskine-arm Jan 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion drivers/builtin/include/mbedtls/private/crypto_adjust_config_tweak_builtins.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,36 @@
*/
#define MBEDTLS_USE_PSA_CRYPTO

/* Whether any Keccak variant is enabled, i.e. the bulk of sha3.c. */
/* Whether any hash based on sha3 is enabled in psa_crypto_hash.c. */
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_224) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_256) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_384) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
#define MBEDTLS_PSA_BUILTIN_ALG_SHA3_SOME_HASH
#endif

/* If a SHAKE variant is enabled in psa_crypto_xof.c, tell sha3.c that we
* want it.
*
* Note that the PSA API (following NIST standards) defines hash algorithms
* that are SHAKE128 or SHAKE256 with a specific output lengths. From the
* perspective of sha3.c, these are just users of SHAKE128/SHAKE256, but
* from the perspective of psa_crypto_hash.c and psa_crypto_xof.c,
* they are hashes and not XOF. So, for example, if the SHAKE256/512 hash
* algorithm is enabled in the PSA API (for Ed448ph) but the SHAKE256 XOF
* algorithm is disabled, then MBEDTLS_PSA_BUILTIN_ALG_SHAKE256 will be
* disabled but we'll still need to enable MBEDTLS_SHA3_WANT_SHAKE256.
*/
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHAKE128)
#define MBEDTLS_SHA3_WANT_SHAKE128
#endif
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHAKE256)
#define MBEDTLS_SHA3_WANT_SHAKE256
#endif
Comment thread
valeriosetti marked this conversation as resolved.

/* Whether any Keccak variant is enabled, i.e. the bulk of sha3.c. */
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_SOME_HASH) || \
defined(MBEDTLS_SHA3_WANT_SHAKE128) || defined(MBEDTLS_SHA3_WANT_SHAKE256)
#define MBEDTLS_SHA3_C
#endif

Expand Down
5 changes: 1 addition & 4 deletions drivers/builtin/include/mbedtls/private/crypto_builtin_primitives.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,10 +72,7 @@ typedef struct {
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA_384)
mbedtls_sha512_context sha512;
#endif
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_224) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_256) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_384) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_SOME_HASH)
mbedtls_sha3_context sha3;
#endif
} MBEDTLS_PRIVATE(ctx);
Expand Down
32 changes: 22 additions & 10 deletions drivers/builtin/include/mbedtls/private/sha3.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* \file sha3.h
*
* \brief This file contains SHA-3 definitions and functions.
* \brief This file contains SHA-3 and SHAKE definitions and functions.
*
* The Secure Hash Algorithms cryptographic
* hash functions are defined in <em>FIPS 202: SHA-3 Standard:
Expand Down Expand Up @@ -30,7 +30,7 @@ extern "C" {

#if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
/**
* SHA-3 family id.
* SHA-3 or SHAKE family id.
*
* It identifies the family (SHA3-256, SHA3-512, etc.)
*/
Expand All @@ -41,6 +41,8 @@ typedef enum {
MBEDTLS_SHA3_256, /*!< SHA3-256 */
MBEDTLS_SHA3_384, /*!< SHA3-384 */
MBEDTLS_SHA3_512, /*!< SHA3-512 */
MBEDTLS_SHA3_SHAKE128, /*!< SHA3-SHAKE128 */
MBEDTLS_SHA3_SHAKE256, /*!< SHA3-SHAKE256 */
} mbedtls_sha3_id;
#endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */

Expand All @@ -54,19 +56,20 @@ typedef struct {
uint32_t MBEDTLS_PRIVATE(index);
uint16_t MBEDTLS_PRIVATE(olen);
uint16_t MBEDTLS_PRIVATE(max_block_size);
uint8_t MBEDTLS_PRIVATE(finished);
}
mbedtls_sha3_context;

#if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
/**
* \brief This function initializes a SHA-3 context.
* \brief This function initializes a SHA-3 or SHAKE context.
*
* \param ctx The SHA-3 context to initialize. This must not be \c NULL.
*/
void mbedtls_sha3_init(mbedtls_sha3_context *ctx);

/**
* \brief This function clears a SHA-3 context.
* \brief This function clears a SHA-3 or SHAKE context.
*
* \param ctx The SHA-3 context to clear. This may be \c NULL, in which
* case this function returns immediately. If it is not \c NULL,
Expand All @@ -75,7 +78,7 @@ void mbedtls_sha3_init(mbedtls_sha3_context *ctx);
void mbedtls_sha3_free(mbedtls_sha3_context *ctx);

/**
* \brief This function clones the state of a SHA-3 context.
* \brief This function clones the state of a SHA-3 or SHAKE context.
*
* \param dst The destination context. This must be initialized.
* \param src The context to clone. This must be initialized.
Expand All @@ -84,11 +87,11 @@ void mbedtls_sha3_clone(mbedtls_sha3_context *dst,
const mbedtls_sha3_context *src);

/**
* \brief This function starts a SHA-3 checksum
* \brief This function starts a SHA-3 checksum or SHAKE XOF
* calculation.
*
* \param ctx The context to use. This must be initialized.
* \param id The id of the SHA-3 family.
* \param id The id of the SHA-3 or SHAKE family.
*
* \return \c 0 on success.
* \return A negative error code on failure.
Expand All @@ -97,7 +100,7 @@ int mbedtls_sha3_starts(mbedtls_sha3_context *ctx, mbedtls_sha3_id id);

/**
* \brief This function feeds an input buffer into an ongoing
* SHA-3 checksum calculation.
* SHA-3 or SHAKE calculation.
*
* \param ctx The SHA-3 context. This must be initialized
* and have a hash operation started.
Expand All @@ -116,13 +119,21 @@ int mbedtls_sha3_update(mbedtls_sha3_context *ctx,
* \brief This function finishes the SHA-3 operation, and writes
* the result to the output buffer.
*
* In a SHA-3 calculation, this function must be called
* exactly once, and \p olen must be the length of the
* hash variant chosen in mbedtls_sha3_starts().
* In a SHAKE calculation, this function may be called
* any number of times to obtain successive chunks of
* the XOF output.
*
* \param ctx The SHA-3 context. This must be initialized
* and have a hash operation started.
* \param output The SHA-3 checksum result.
* This must be a writable buffer of length \c olen bytes.
* \param olen Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256,
* SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64,
* respectively.
* For SHAKE128 and SHAKE256 it can be an arbitrary number.
*
* \return \c 0 on success.
* \return A negative error code on failure.
Expand All @@ -131,8 +142,8 @@ int mbedtls_sha3_finish(mbedtls_sha3_context *ctx,
uint8_t *output, size_t olen);

/**
* \brief This function calculates the SHA-3
* checksum of a buffer.
* \brief This function calculates the SHA-3 checksum
* or XOF output of a buffer.
*
* The function allocates the context, performs the
* calculation, and frees the context.
Expand All @@ -149,6 +160,7 @@ int mbedtls_sha3_finish(mbedtls_sha3_context *ctx,
* \param olen Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256,
* SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64,
* respectively.
* For SHAKE128 and SHAKE256 it can be an arbitrary number.
*
* \return \c 0 on success.
* \return A negative error code on failure.
Expand Down
20 changes: 4 additions & 16 deletions drivers/builtin/src/psa_crypto_hash.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,10 +74,7 @@ psa_status_t mbedtls_psa_hash_abort(
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
case PSA_ALG_SHA3_512:
#endif
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_224) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_256) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_384) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_SOME_HASH)
mbedtls_sha3_free(&operation->ctx.sha3);
break;
#endif
Expand Down Expand Up @@ -240,10 +237,7 @@ psa_status_t mbedtls_psa_hash_clone(
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
case PSA_ALG_SHA3_512:
#endif
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_224) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_256) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_384) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_SOME_HASH)
mbedtls_sha3_clone(&target_operation->ctx.sha3,
&source_operation->ctx.sha3);
break;
Expand Down Expand Up @@ -320,10 +314,7 @@ psa_status_t mbedtls_psa_hash_update(
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
case PSA_ALG_SHA3_512:
#endif
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_224) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_256) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_384) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_SOME_HASH)
ret = mbedtls_sha3_update(&operation->ctx.sha3,
input, input_length);
break;
Expand Down Expand Up @@ -410,10 +401,7 @@ psa_status_t mbedtls_psa_hash_finish(
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
case PSA_ALG_SHA3_512:
#endif
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_224) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_256) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_384) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_512)
#if defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_SOME_HASH)
ret = mbedtls_sha3_finish(&operation->ctx.sha3, hash, hash_size);
break;
#endif
Expand Down
Loading