Document additional sha3 functions.

2 files changed, 117 insertions, 11 deletions

diff --git a/ChangeLog b/ChangeLog
index 28c4712a..110342df 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
 2013-01-01  Niels Möller  <nisse@lysator.liu.se>
 
+	* nettle.texinfo (Recommended hash functions): Document additional
+	sha3 functions.
+
 	* examples/nettle-benchmark.c (main): Benchmark additional sha3
 	functions.
 
diff --git a/nettle.texinfo b/nettle.texinfo
index f358d100..d8d6119a 100644
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -542,23 +542,59 @@ This function also resets the context in the same way as
 @code{sha384_init}.
 @end deftypefun
 
-@subsubsection @acronym{SHA3-256}
+@subsubsection @acronym{SHA3-224}
 
 The SHA3 hash functions were specified by NIST in repsonse to weaknesses
-in SHA1, and doubts about SHA2 hashfunctions which structurally are very
-similar to SHA1. The standard is a result of a competition, where the
-winning design, also known as Keccak, was designed by Guido Bertoni,
-Joan Daemen, Michaël Peeters and Gilles Van Assche. It is structurally
-very different from all widely used earlier hash functions. Nettle's
-current implementation is pretty slow.
+in SHA1, and doubts about SHA2 hash functions which structurally are
+very similar to SHA1. The standard is a result of a competition, where
+the winner, also known as Keccak, was designed by Guido Bertoni, Joan
+Daemen, Michaël Peeters and Gilles Van Assche. It is structurally very
+different from all widely used earlier hash functions. Like SHA2, there
+are several variants, with output sizes of 224, 256, 384 and 512 bits
+(28, 32, 48 and 64 octets, respectively).
 
-Nettle defines SHA3-256 in @file{<nettle/sha3.h>}.
+Nettle defines SHA3-224 in @file{<nettle/sha3.h>}.
 
 @deftp {Context struct} {struct sha3_224_ctx}
 @end deftp
 
+@defvr Constant SHA3_224_DIGEST_SIZE
+The size of a SHA3_224 digest, i.e., 28.
+@end defvr
+
+@defvr Constant SHA3_224_DATA_SIZE
+The internal block size of SHA3_224.
+@end defvr
+
+@deftypefun void sha3_224_init (struct sha3_224_ctx *@var{ctx})
+Initialize the SHA3-224 state.
+@end deftypefun
+
+@deftypefun void sha3_224_update (struct sha3_224_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
+Hash some more data.
+@end deftypefun
+
+@deftypefun void sha3_224_digest (struct sha3_224_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
+Performs final processing and extracts the message digest, writing it
+to @var{digest}. @var{length} may be smaller than
+@code{SHA3_224_DIGEST_SIZE}, in which case only the first @var{length}
+octets of the digest are written.
+
+This function also resets the context.
+@end deftypefun
+
+@subsubsection @acronym{SHA3-256}
+
+This is SHA3 with 256-bit output size, and possibly the most useful
+of the SHA3 hash functions.
+
+Nettle defines SHA3-256 in @file{<nettle/sha3.h>}.
+
+@deftp {Context struct} {struct sha3_256_ctx}
+@end deftp
+
 @defvr Constant SHA3_256_DIGEST_SIZE
-The size of an SHA3_256 digest, i.e. 32.
+The size of a SHA3_256 digest, i.e., 32.
 @end defvr
 
 @defvr Constant SHA3_256_DATA_SIZE
@@ -579,8 +615,75 @@ to @var{digest}. @var{length} may be smaller than
 @code{SHA3_256_DIGEST_SIZE}, in which case only the first @var{length}
 octets of the digest are written.
 
-This function also resets the context in the same way as
-@code{sha3_256_init}.
+This function also resets the context.
+@end deftypefun
+
+@subsubsection @acronym{SHA3-384}
+
+This is SHA3 with 384-bit output size.
+
+Nettle defines SHA3-384 in @file{<nettle/sha3.h>}.
+
+@deftp {Context struct} {struct sha3_384_ctx}
+@end deftp
+
+@defvr Constant SHA3_384_DIGEST_SIZE
+The size of a SHA3_384 digest, i.e., 48.
+@end defvr
+
+@defvr Constant SHA3_384_DATA_SIZE
+The internal block size of SHA3_384.
+@end defvr
+
+@deftypefun void sha3_384_init (struct sha3_384_ctx *@var{ctx})
+Initialize the SHA3-384 state.
+@end deftypefun
+
+@deftypefun void sha3_384_update (struct sha3_384_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
+Hash some more data.
+@end deftypefun
+
+@deftypefun void sha3_384_digest (struct sha3_384_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
+Performs final processing and extracts the message digest, writing it
+to @var{digest}. @var{length} may be smaller than
+@code{SHA3_384_DIGEST_SIZE}, in which case only the first @var{length}
+octets of the digest are written.
+
+This function also resets the context.
+@end deftypefun
+
+@subsubsection @acronym{SHA3-512}
+
+This is SHA3 with 512-bit output size.
+
+Nettle defines SHA3-512 in @file{<nettle/sha3.h>}.
+
+@deftp {Context struct} {struct sha3_512_ctx}
+@end deftp
+
+@defvr Constant SHA3_512_DIGEST_SIZE
+The size of a SHA3_512 digest, i.e. 64.
+@end defvr
+
+@defvr Constant SHA3_512_DATA_SIZE
+The internal block size of SHA3_512.
+@end defvr
+
+@deftypefun void sha3_512_init (struct sha3_512_ctx *@var{ctx})
+Initialize the SHA3-512 state.
+@end deftypefun
+
+@deftypefun void sha3_512_update (struct sha3_512_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
+Hash some more data.
+@end deftypefun
+
+@deftypefun void sha3_512_digest (struct sha3_512_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
+Performs final processing and extracts the message digest, writing it
+to @var{digest}. @var{length} may be smaller than
+@code{SHA3_512_DIGEST_SIZE}, in which case only the first @var{length}
+octets of the digest are written.
+
+This function also resets the context.
 @end deftypefun
 
 @node Legacy hash functions, nettle_hash abstraction, Recommended hash functions, Hash functions