Commit fd0413bb authored by Niels Möller's avatar Niels Möller

Document additional sha3 functions.

parent 61002bdb
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.
......
......@@ -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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment