diff --git a/ChangeLog b/ChangeLog index 28c4712a8b341d853e807b7b2ccb26668516eb8d..110342dfd09f27812f517759439b0189109ffd6e 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 f358d100159403134c7067ca756352e457fa864d..d8d6119ae3ad66539c9e13d9e0bf7a228551c2b5 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