Sorry for the late response. Niels Möller <[email protected]> writes:
>>> 2. Implement shake128. >> >> I've extracted it from the ML-KEM merge request and put it here: >> https://git.lysator.liu.se/nettle/nettle/-/merge_requests/63 >> >> Not sending via email as it includes a huge test vector. > > Thanks, merged to the sha3-shake-updates branch. Sorry if you didn't > intend me to do that right away (I noticed some minor problems after > merge, which I've fixed). I'd like to merge to master after ci runs have > completed. Thank you for merging it (with the fixes); I wasn't actually aware of the problems. >>> 3. Update docs. >> >> I can do that once we settle the interface. > > Excellent. To me, interface in sha3.h now looks good. I'm attaching a patch to update the documentation. Regards, -- Daiki Ueno
>From da9c6bea06043d37c895233ca35d5b9c7fb029b5 Mon Sep 17 00:00:00 2001 From: Daiki Ueno <[email protected]> Date: Thu, 11 Apr 2024 17:51:39 +0900 Subject: [PATCH] Update documentation for SHAKE Signed-off-by: Daiki Ueno <[email protected]> --- nettle.texinfo | 67 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 59 insertions(+), 8 deletions(-) diff --git a/nettle.texinfo b/nettle.texinfo index 95e89971..85a3a6b5 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -755,28 +755,79 @@ octets of the digest are written. This function also resets the context. @end deftypefun -@subsubsection @acronym{SHAKE-256} +@subsubsection @acronym{SHAKE-128} @cindex SHAKE -In addition to those SHA-3 hash functions, Nettle also provides a SHA-3 -extendable-output function (XOF), SHAKE-256. Unlike SHA-3 hash functions, -SHAKE can produce an output digest of any desired length. +In addition to those SHA-3 hash functions, Nettle also provides a +SHA-3 extendable-output function (XOF) called SHAKE. Unlike hash +functions, SHAKE can produce an output digest of any desired +length. There are two variants, SHAKE-128 and SHAKE-256, with +different security strengths in terms of collision or preimage +resistance. + +SHAKE-128 internally uses a SHA-3 hash function with 128-bit security +strength against second preimage attacks. The hash function is not +usable alone with Nettle, only for the use with SHAKE-128. + +Nettle defines context struct, init and update functions in +@file{<nettle/sha3.h>}. + +@deftp {Context struct} {struct sha3_128_ctx} +@end deftp + +@deftypefun void sha3_128_init (struct sha3_128_ctx *@var{ctx}) +Initialize the SHA3-256 state. +@end deftypefun + +@deftypefun void sha3_128_update (struct sha3_128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) +Hash some more data. +@end deftypefun + +After all data is fed into the context, the following functions can be +used to generate the output. + +@deftypefun void sha3_128_shake (struct sha3_128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) +Performs final processing and produces a SHAKE-128 digest, writing it +to @var{digest}. @var{length} can be of arbitrary size. -To use SHAKE256, the context struct, init and update functions are the -same as for SHA3-256. To get a SHAKE256 digest, the following function +This function also resets the context. +@end deftypefun + +@deftypefun void sha3_128_shake_output (struct sha3_128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) +Performs final processing and produces a SHAKE-128 digest, writing it +to @var{digest}. @var{length} can be of arbitrary size. + +Unlike @code{sha3_128_shake}, this function doesn't reset the context +and thus can be called multiple times to retrieve output in an +incremental manner. +@end deftypefun + +@subsubsection @acronym{SHAKE-256} + +To use SHAKE-256, the context struct, init and update functions are the +same as for SHA3-256. To get a SHAKE-256 digest, the following function is used instead of @code{sha3_256_digest}. For an output size of @code{SHA3_256_DIGEST_SIZE}, security is equivalent to SHA3-256 (but the digest is different). Increasing output size further does not increase security in terms of collision or preimage resistance. It can be seen as a built in pseudorandomness generator. -@deftypefun void sha3_256_shake (struct shake256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) -Performs final processing and produces a SHAKE256 digest, writing it +@deftypefun void sha3_256_shake (struct sha3_256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) +Performs final processing and produces a SHAKE-256 digest, writing it to @var{digest}. @var{length} can be of arbitrary size. This function also resets the context. @end deftypefun +@deftypefun void sha3_256_shake_output (struct sha3_256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) +Performs final processing and produces a SHAKE-256 digest, writing it +to @var{digest}. @var{length} can be of arbitrary size. + +Unlike @code{sha3_256_shake}, this function doesn't reset the context +and thus can be called multiple times to retrieve output in an +incremental manner. +@end deftypefun + @node Miscellaneous hash functions @subsection Miscellaneous hash functions -- 2.44.0
_______________________________________________ nettle-bugs mailing list -- [email protected] To unsubscribe send an email to [email protected]
