Implement SHAKE in sha3.c by gilles-peskine-arm · Pull Request #648 · Mbed-TLS/TF-PSA-Crypto

gilles-peskine-arm · 2026-01-09T17:30:16Z

Implement SHAKE in the SHA3 module. Resolves #621

An earlier version of this pull request also implemented the SHAKE128/256 and SHAKE256/512 hash algorithms. We don't need those urgently: they'll be needed for HashML-DSA and for Ed448ph respectively. That part is at https://github.com/gilles-peskine-arm/TF-PSA-Crypto/tree/sha3-shake-builtin-2 (with unresolved problems with some test driver builds) and needs preceding PR: Mbed-TLS/mbedtls-framework#267.

PR checklist

changelog no (nothing user-visible)
framework PR not required
mbedtls development PR not required because: crypto only
mbedtls 3.6 PR not required because: new feature
tests provided

bjwtaylor

One quick question, though still need to review in more detail when I get a chance.

bjwtaylor · 2026-01-13T12:00:28Z

            break;
 #endif
+
+#if defined(MBEDTLS_SHA3_WANT_SHAKE128)


Should the SHAKE variants be setting the ctx->olen to 0, to clear it to prevent any prior length being retained?

Yes, that's a good idea. And that shows we're missing a context reuse test case for SHAKE.

More precisely, the case where it can go wrong is if there's a non-SHAKE operation without finish, then a SHAKE operation. The SHAKE operation will be limited to a single finish() call, which will output exactly the length of the hash from the first operation. We aren't currently testing a context reuse without finish (i.e. init, starts, update, starts, update, finish).

bjwtaylor · 2026-01-14T15:35:03Z

 /*
 * SHA-3 process buffer
 */
 int mbedtls_sha3_update(mbedtls_sha3_context *ctx,


Should this function check for the presence of ctx->finished to prevent an API misuse of using an update after a finish and produce an error if it is set?

Ideally yes, but this is now a private interface.

It would be good to do that in 3.6 though, since sha3.h is public there.

As discussed on Thursday, this is an internal interface, we don't particularly need to protect against misuse.

bjwtaylor · 2026-01-14T15:37:50Z

+#endif /* defined(MBEDTLS_PSA_BUILTIN_ALG_SHA3_SOME_HASH) */
+
+#if defined(MBEDTLS_SHA3_WANT_SHAKE128)
+static const unsigned char shake128_test_input[2][16] =


Do we document anywhere where this test data comes from?

Should, yes. Do, unfortunately, no. But we don't actually rely on it for correctness (we have the unit tests for that), so I can live with it.

Yeah, I was more thinking if anybody has to modify it or wants to use it for other tests it's useful to know where it comes from.

valeriosetti

I found only a minor typo in a comment, but the rest LGTM.

This is in preparation for adding SHAKE support: if e.g. SHAKE128 is enabled but no SHA3 hash, then psa_crypto_hash.c should not include SHA3 support. Conversely, if e.g. SHAKE128/256 is enabled but neither SHAKE128 nor SHAKE256, then psa_crypto_xof.c should not include SHAKE support. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

We don't have a XOF API yet in PSA. To provide a way to enable built-in SHAKE support, for now, add options to `crypto_config.h` that are enabled in the `full` config. Define the MBEDTLS_PSA_BUILTIN_xxx symbols as macros with no parameter, rather than with the value 1 as usual, so that `config.py full` enables them. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Signed-off-by: Pol Henarejos <pol.henarejos@cttc.es> Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

SHAKE, as it is a XOF function, it allows arbitrary output lengths that can be called multiple times and concatenated. The property SHAKE_finish(olen1+olen2)=SHAKE_finish(olen1)||SHAKE_finish(olen2) always holds. Signed-off-by: Pol Henarejos <pol.henarejos@cttc.es> Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Signed-off-by: Pol Henarejos <pol.henarejos@cttc.es> Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Choose some representative lengths: 0, a few short inputs, one block -1/+0/+1, two blocks -1/+0/+1. Test cases generated by the following Python code: ``` from hashlib import shake_128, shake_256; def tc(f, shake, v, n): msg = shake(bytes(str(n), encoding="ascii")).digest(n); output = shake(msg).digest(300); return f"SHAKE{v} {f} {n}\ndepends_on:MBEDTLS_SHA3_WANT_SHAKE{v}\nshake_{f}:MBEDTLS_SHA3_SHAKE{v}:\"{msg.hex()}\":\"{output.hex()}\":\n" for n in [0, 1, 2, 4, 8, 16, 42, 55, 100, 167, 168, 169, 335, 336, 337]: print(tc("input", shake_128, 128, n)) for n in [0, 1, 2, 4, 8, 16, 42, 55, 100, 135, 136, 137, 271, 272, 273]: print(tc("input", shake_256, 256, n)) for n in [0, 1, 200]: print(tc("output", shake_128, 128, n)) for n in [0, 1, 200]: print(tc("output", shake_256, 256, n)) ``` Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Test data from NIST: https://github.com/usnistgov/ACVP-Server/blob/v1.1.0.41/gen-val/json-files/SHAKE-128-FIPS202/internalProjection.json https://github.com/usnistgov/ACVP-Server/blob/v1.1.0.41/gen-val/json-files/SHAKE-256-FIPS202/internalProjection.json Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

gilles-peskine-arm · 2026-01-19T12:14:01Z

I rewrote the history to remove the framework update commit, since it isn't needed after all. I also fixed the typo that Valerio pointed out while I was at it. The previous version is at https://github.com/gilles-peskine-arm/TF-PSA-Crypto/tree/sha3-shake-builtin-4

gilles-peskine-arm added the size-s Estimated task size: small (~2d) label Jan 9, 2026

gilles-peskine-arm added this to Roadmap pull requests (new board) Jan 9, 2026

gilles-peskine-arm added priority-high High priority - will be reviewed soon needs-preceding-pr Requires another PR to be merged first needs-design-approval Needs design discussion / approval needs-ci Needs to pass CI tests labels Jan 9, 2026

github-project-automation Bot moved this to In Development in Roadmap pull requests (new board) Jan 9, 2026

gilles-peskine-arm mentioned this pull request Jan 9, 2026

Framework support for SHAKE128/256 and SHAKE256/512 Mbed-TLS/mbedtls-framework#267

Open

3 tasks

gilles-peskine-arm force-pushed the sha3-shake-builtin branch from d383661 to b777b99 Compare January 12, 2026 12:06

gilles-peskine-arm removed the needs-design-approval Needs design discussion / approval label Jan 12, 2026

gilles-peskine-arm changed the title ~~Implement SHAKE in sha3.c, and add SHAKE128/256 and SHAKE256/512 hash algorithms~~ Implement SHAKE in sha3.c Jan 12, 2026

gilles-peskine-arm removed the needs-preceding-pr Requires another PR to be merged first label Jan 12, 2026

gilles-peskine-arm force-pushed the sha3-shake-builtin branch 2 times, most recently from 55b4391 to 54a0ef2 Compare January 12, 2026 12:18

gilles-peskine-arm mentioned this pull request Jan 12, 2026

Support SHAKE128/256 and SHAKE256/512 hash algorithms #651

Open

gilles-peskine-arm marked this pull request as ready for review January 13, 2026 08:37

gilles-peskine-arm added needs-review Every commit must be reviewed by at least two team members and removed needs-ci Needs to pass CI tests labels Jan 13, 2026

gilles-peskine-arm requested review from bjwtaylor and valeriosetti January 13, 2026 08:37

bjwtaylor reviewed Jan 13, 2026

View reviewed changes

valeriosetti requested changes Jan 13, 2026

View reviewed changes

Comment thread drivers/builtin/src/sha3.c

Comment thread drivers/builtin/include/mbedtls/private/crypto_adjust_config_tweak_builtins.h

bjwtaylor reviewed Jan 14, 2026

View reviewed changes

gilles-peskine-arm requested review from bjwtaylor and valeriosetti January 19, 2026 07:55

valeriosetti previously approved these changes Jan 19, 2026

View reviewed changes

Comment thread drivers/builtin/include/mbedtls/private/crypto_adjust_config_tweak_builtins.h Outdated

bjwtaylor previously approved these changes Jan 19, 2026

View reviewed changes

github-project-automation Bot moved this from In Development to Has Approval in Roadmap pull requests (new board) Jan 19, 2026

valeriosetti added approved Design and code approved - may be waiting for CI or backports and removed needs-review Every commit must be reviewed by at least two team members labels Jan 19, 2026

valeriosetti removed the approved Design and code approved - may be waiting for CI or backports label Jan 19, 2026

gilles-peskine-arm and others added 14 commits January 19, 2026 13:12

Adding SHA-3 SHAKE128 and SHA-3 SHAKE256.

5ba3c76

Signed-off-by: Pol Henarejos <pol.henarejos@cttc.es> Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Don't free the context in finish() when doing SHAKE

b297452

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Add self tests for SHAKE

6f2a453

Signed-off-by: Pol Henarejos <pol.henarejos@cttc.es> Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Don't try to build and run SHAKE self-test when SHAKE is disabled

54f761e

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Update sha3.h documentation for SHAKE

e6b87da

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Test SHA3/SHAKE with empty input, with or without an update() call

3988f04

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Fix build failure with some SHAKE but no SHA3 hash

239a07d

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Explain why MBEDTLS_SHA3_WANT_SHAKEnnn ≠ MBEDTLS_PSA_BUILTIN_SHAKEnnn

2e0cbd8

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Simplify context reuse protection in mbedtls_sha3_starts

4c973cf

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

gilles-peskine-arm dismissed stale reviews from bjwtaylor and valeriosetti via 4c973cf January 19, 2026 12:12

gilles-peskine-arm force-pushed the sha3-shake-builtin branch from 9ff5c39 to 4c973cf Compare January 19, 2026 12:12

gilles-peskine-arm added needs-review Every commit must be reviewed by at least two team members and removed needs-work labels Jan 19, 2026

valeriosetti approved these changes Jan 19, 2026

View reviewed changes

gilles-peskine-arm requested a review from bjwtaylor January 19, 2026 16:04

bjwtaylor approved these changes Jan 20, 2026

View reviewed changes

valeriosetti added approved Design and code approved - may be waiting for CI or backports and removed needs-review Every commit must be reviewed by at least two team members labels Jan 20, 2026

valeriosetti added this pull request to the merge queue Jan 20, 2026

Merged via the queue into Mbed-TLS:development with commit dc5a2f2 Jan 20, 2026
2 checks passed

github-project-automation Bot moved this from Has Approval to Done in Roadmap pull requests (new board) Jan 20, 2026

Conversation

gilles-peskine-arm commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR checklist

Uh oh!

bjwtaylor left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

valeriosetti left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gilles-peskine-arm commented Jan 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gilles-peskine-arm commented Jan 9, 2026 •

edited

Loading