Document SHAKE-256.

diff --git a/ChangeLog b/ChangeLog
index d5b2e2ff63ed3f316ed73ba3f0c47395524b6292..aa3bbfc0fa11589ee7f038ce2731254f5670ce85 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -8,6 +8,7 @@
        * testsuite/shake.awk: New script to extract test vectors.
        * testsuite/Makefile.in (TS_NETTLE_SOURCES): Add shake256-test.c.
        (DISTFILES): Add shake.awk.
+       * nettle.texinfo (Recommended hash functions): Document SHAKE-256.
 
        * sha3.c (_sha3_pad): Generalized with an argument for the magic
        suffix defining the sha3 instance.

diff --git a/nettle.texinfo b/nettle.texinfo
index 5eb5752dc7af94012e0cebfc9f77d55591846491..2df85e77faf9fe00725d4ed4d90e4e462a5a1dff 100644 (file)
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -834,6 +834,28 @@ octets of the digest are written.
 This function also resets the context.
 @end deftypefun
 
+@subsubsection @acronym{SHAKE-256}
+@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.
+
+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
+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
+to @var{digest}. @var{length} can be of arbitrary size.
+
+This function also resets the context.
+@end deftypefun
+
 @node Legacy hash functions, nettle_hash abstraction, Recommended hash functions, Hash functions
 @comment  node-name,  next,  previous,  up
 @subsection Legacy hash functions