From: Niels Möller <nisse@lysator.liu.se>
Date: Wed, 25 Dec 2019 18:55:17 +0000 (+0100)
Subject: Document SHAKE-256.
X-Git-Tag: nettle_3.6rc1~56
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0e1108ba872a11e1cc9d55aecc1f564d9c265c7a;p=thirdparty%2Fnettle.git

Document SHAKE-256.
---

diff --git a/ChangeLog b/ChangeLog
index d5b2e2ff..aa3bbfc0 100644
--- 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 5eb5752d..2df85e77 100644
--- 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