diff --git a/ChangeLog b/ChangeLog index 0790560630877f5e353bb6647ca508a4d5bf29f8..d14403fad15f0b9d201cdaffdec1e3c25a80965b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2012-12-03 Niels Möller + + * nettle.texinfo (Hash functions): Split into several sections, + separating recommended hash functions and legacy hash functions. + Document sha3-256. + 2012-12-02 Niels Möller Split sha.h into new files sha1.h and sha2.h. Replaced all diff --git a/nettle.texinfo b/nettle.texinfo index 025c783870963ac8e4496ff461997a01994dfa8a..f358d100159403134c7067ca756352e457fa864d 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -7,14 +7,14 @@ @syncodeindex fn cp @c %**end of header -@set UPDATED-FOR 2.5 +@set UPDATED-FOR 2.6 @set AUTHOR Niels Möller @copying This manual is for the Nettle library (version @value{UPDATED-FOR}), a low-level cryptographic library. -Originally written 2001 by @value{AUTHOR}, updated 2011. +Originally written 2001 by @value{AUTHOR}, updated 2012. @quotation This manual is placed in the public domain. You may freely copy it, in @@ -220,6 +220,9 @@ released under the LGPL. Written by @value{AUTHOR}, using Peter Gutmann's SHA1 code as a model. Released under the LGPL. +@item SHA3-256 +Written by @value{AUTHOR}. Released under the LGPL. + @item GOSTHASH94 The C implementation of the GOST94 message digest is written by Aleksey Kravchenko and was ported from the rhash library by Nikos @@ -294,7 +297,7 @@ Nettle. On a typical Unix system, this program can be compiled and linked with the command line @example -cc sha-example.c -o sha-example -lnettle +gcc sha-example.c -o sha-example -lnettle @end example @node Linking, Reference, Example, Top @@ -336,6 +339,7 @@ This chapter describes all the Nettle functions, grouped by family. @node Hash functions, Cipher functions, Reference, Reference @comment node-name, next, previous, up + @section Hash functions @cindex Hash function A cryptographic @dfn{hash function} is a function that takes variable @@ -365,358 +369,426 @@ unique ids to documents, and many other things. The most commonly used hash functions are MD5 and SHA1. Unfortunately, both these fail the collision-resistance requirement; cryptologists have -found ways to construct colliding inputs. The recommended hash function -for new applications is SHA256, even though it uses a structure similar -to MD5 and SHA1. Constructing better hash functions is an urgent research -problem. +found ways to construct colliding inputs. The recommended hash functions +for new applications are SHA2 (with main variants SHA256 and SHA512). At +the time of this writing (December 2012), the winner of the NIST SHA3 +competition has recently been announced, and the new SHA3 (earlier known +as Keccak) and other top SHA3 candidates may also be reasonable +alternatives. -@subsection @acronym{MD5} +@menu +* Recommended hash functions:: +* Legacy hash functions:: +* nettle_hash abstraction:: +@end menu -MD5 is a message digest function constructed by Ronald Rivest, and -described in @cite{RFC 1321}. It outputs message digests of 128 bits, or -16 octets. Nettle defines MD5 in @file{}. +@node Recommended hash functions, Legacy hash functions,, Hash functions +@comment node-name, next, previous, up +@subsection Recommended hash functions -@deftp {Context struct} {struct md5_ctx} +The following hash functions have no known weaknesses, and are suitable +for new applications. The SHA2 family of hash functions were specified +by @dfn{NIST}, intended as a replacement for @acronym{SHA1}. + +@subsubsection @acronym{SHA256} + +SHA256 is a member of the SHA2 family. It outputs hash values of 256 +bits, or 32 octets. Nettle defines SHA256 in @file{}. + +@deftp {Context struct} {struct sha256_ctx} @end deftp -@defvr Constant MD5_DIGEST_SIZE -The size of an MD5 digest, i.e. 16. +@defvr Constant SHA256_DIGEST_SIZE +The size of an SHA256 digest, i.e. 32. @end defvr -@defvr Constant MD5_DATA_SIZE -The internal block size of MD5. Useful for some special constructions, -in particular HMAC-MD5. +@defvr Constant SHA256_DATA_SIZE +The internal block size of SHA256. Useful for some special constructions, +in particular HMAC-SHA256. @end defvr -@deftypefun void md5_init (struct md5_ctx *@var{ctx}) -Initialize the MD5 state. +@deftypefun void sha256_init (struct sha256_ctx *@var{ctx}) +Initialize the SHA256 state. @end deftypefun -@deftypefun void md5_update (struct md5_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +@deftypefun void sha256_update (struct sha256_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) Hash some more data. @end deftypefun -@deftypefun void md5_digest (struct md5_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) +@deftypefun void sha256_digest (struct sha256_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{MD5_DIGEST_SIZE}, in which case only the first @var{length} +@code{SHA256_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{md5_init}. +@code{sha256_init}. @end deftypefun -The normal way to use MD5 is to call the functions in order: First -@code{md5_init}, then @code{md5_update} zero or more times, and finally -@code{md5_digest}. After @code{md5_digest}, the context is reset to -its initial state, so you can start over calling @code{md5_update} to -hash new data. - -To start over, you can call @code{md5_init} at any time. +Earlier versions of nettle defined SHA256 in the header file +@file{}, which is now deprecated, but kept for +compatibility. -@subsection @acronym{MD2} +@subsubsection @acronym{SHA224} -MD2 is another hash function of Ronald Rivest's, described in -@cite{RFC 1319}. It outputs message digests of 128 bits, or 16 octets. -Nettle defines MD2 in @file{}. +SHA224 is a variant of SHA256, with a different initial state, and with +the output truncated to 224 bits, or 28 octets. Nettle defines SHA224 in +@file{} (and in @file{}, for backwards +compatibility). -@deftp {Context struct} {struct md2_ctx} +@deftp {Context struct} {struct sha224_ctx} @end deftp -@defvr Constant MD2_DIGEST_SIZE -The size of an MD2 digest, i.e. 16. +@defvr Constant SHA224_DIGEST_SIZE +The size of an SHA224 digest, i.e. 28. @end defvr -@defvr Constant MD2_DATA_SIZE -The internal block size of MD2. +@defvr Constant SHA224_DATA_SIZE +The internal block size of SHA224. Useful for some special constructions, +in particular HMAC-SHA224. @end defvr -@deftypefun void md2_init (struct md2_ctx *@var{ctx}) -Initialize the MD2 state. +@deftypefun void sha224_init (struct sha224_ctx *@var{ctx}) +Initialize the SHA224 state. @end deftypefun -@deftypefun void md2_update (struct md2_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +@deftypefun void sha224_update (struct sha224_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) Hash some more data. @end deftypefun -@deftypefun void md2_digest (struct md2_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) +@deftypefun void sha224_digest (struct sha224_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{MD2_DIGEST_SIZE}, in which case only the first @var{length} +@code{SHA224_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{md2_init}. +@code{sha224_init}. @end deftypefun -@subsection @acronym{MD4} +@subsubsection @acronym{SHA512} -MD4 is a predecessor of MD5, described in @cite{RFC 1320}. Like MD5, it -is constructed by Ronald Rivest. It outputs message digests of 128 bits, -or 16 octets. Nettle defines MD4 in @file{}. Use of MD4 is -not recommended, but it is sometimes needed for compatibility with -existing applications and protocols. +SHA512 is a larger sibling to SHA256, with a very similar structure but +with both the output and the internal variables of twice the size. The +internal variables are 64 bits rather than 32, making it significantly +slower on 32-bit computers. It outputs hash values of 512 bits, or 64 +octets. Nettle defines SHA512 in @file{} (and in +@file{}, for backwards compatibility). -@deftp {Context struct} {struct md4_ctx} +@deftp {Context struct} {struct sha512_ctx} @end deftp -@defvr Constant MD4_DIGEST_SIZE -The size of an MD4 digest, i.e. 16. +@defvr Constant SHA512_DIGEST_SIZE +The size of an SHA512 digest, i.e. 64. @end defvr -@defvr Constant MD4_DATA_SIZE -The internal block size of MD4. +@defvr Constant SHA512_DATA_SIZE +The internal block size of SHA512. Useful for some special constructions, +in particular HMAC-SHA512. @end defvr -@deftypefun void md4_init (struct md4_ctx *@var{ctx}) -Initialize the MD4 state. +@deftypefun void sha512_init (struct sha512_ctx *@var{ctx}) +Initialize the SHA512 state. @end deftypefun -@deftypefun void md4_update (struct md4_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +@deftypefun void sha512_update (struct sha512_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) Hash some more data. @end deftypefun -@deftypefun void md4_digest (struct md4_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) +@deftypefun void sha512_digest (struct sha512_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{MD4_DIGEST_SIZE}, in which case only the first @var{length} +@code{SHA512_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{md4_init}. +@code{sha512_init}. @end deftypefun -@subsection @acronym{RIPEMD160} +@subsubsection @acronym{SHA384} -RIPEMD160 is a hash function designed by Hans Dobbertin, Antoon -Bosselaers, and Bart Preneel, as a strengthened version of RIPEMD -(which, like MD4 and MD5, fails the collision-resistance requirement). -It produces message digests of 160 bits, or 20 octets. Nettle defined -RIPEMD160 in @file{nettle/ripemd160.h}. +SHA384 is a variant of SHA512, with a different initial state, and with +the output truncated to 384 bits, or 48 octets. Nettle defines SHA384 in +@file{} (and in @file{}, for backwards +compatibility). -@deftp {Context struct} {struct ripemd160_ctx} +@deftp {Context struct} {struct sha384_ctx} @end deftp -@defvr Constant RIPEMD160_DIGEST_SIZE -The size of an RIPEMD160 digest, i.e. 20. +@defvr Constant SHA384_DIGEST_SIZE +The size of an SHA384 digest, i.e. 48. @end defvr -@defvr Constant RIPEMD160_DATA_SIZE -The internal block size of RIPEMD160. +@defvr Constant SHA384_DATA_SIZE +The internal block size of SHA384. Useful for some special constructions, +in particular HMAC-SHA384. @end defvr -@deftypefun void ripemd160_init (struct ripemd160_ctx *@var{ctx}) -Initialize the RIPEMD160 state. +@deftypefun void sha384_init (struct sha384_ctx *@var{ctx}) +Initialize the SHA384 state. @end deftypefun -@deftypefun void ripemd160_update (struct ripemd160_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +@deftypefun void sha384_update (struct sha384_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) Hash some more data. @end deftypefun -@deftypefun void ripemd160_digest (struct ripemd160_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) +@deftypefun void sha384_digest (struct sha384_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{RIPEMD160_DIGEST_SIZE}, in which case only the first @var{length} +@code{SHA384_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{ripemd160_init}. +@code{sha384_init}. @end deftypefun -@subsection @acronym{SHA1} +@subsubsection @acronym{SHA3-256} -SHA1 is a hash function specified by @dfn{NIST} (The U.S. National Institute -for Standards and Technology). It outputs hash values of 160 bits, or 20 -octets. Nettle defines SHA1 in @file{}. +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. -The functions are analogous to the MD5 ones. +Nettle defines SHA3-256 in @file{}. -@deftp {Context struct} {struct sha1_ctx} +@deftp {Context struct} {struct sha3_224_ctx} @end deftp -@defvr Constant SHA1_DIGEST_SIZE -The size of an SHA1 digest, i.e. 20. +@defvr Constant SHA3_256_DIGEST_SIZE +The size of an SHA3_256 digest, i.e. 32. @end defvr -@defvr Constant SHA1_DATA_SIZE -The internal block size of SHA1. Useful for some special constructions, -in particular HMAC-SHA1. +@defvr Constant SHA3_256_DATA_SIZE +The internal block size of SHA3_256. @end defvr -@deftypefun void sha1_init (struct sha1_ctx *@var{ctx}) -Initialize the SHA1 state. +@deftypefun void sha3_256_init (struct sha3_256_ctx *@var{ctx}) +Initialize the SHA3-256 state. @end deftypefun -@deftypefun void sha1_update (struct sha1_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +@deftypefun void sha3_256_update (struct sha3_256_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) Hash some more data. @end deftypefun -@deftypefun void sha1_digest (struct sha1_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) +@deftypefun void sha3_256_digest (struct sha3_256_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{SHA1_DIGEST_SIZE}, in which case only the first @var{length} +@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{sha1_init}. +@code{sha3_256_init}. @end deftypefun -@subsection @acronym{SHA256} +@node Legacy hash functions, nettle_hash abstraction, Recommended hash functions, Hash functions +@comment node-name, next, previous, up +@subsection Legacy hash functions -SHA256 is another hash function specified by @dfn{NIST}, intended as a -replacement for @acronym{SHA1}, generating larger digests. It outputs -hash values of 256 bits, or 32 octets. Nettle defines SHA256 in -@file{}. +The hash functions in this section all have some known weaknesses, and +should be avoided for new applications. These hash functions are mainly +useful for compatibility with old applications and protocols. Some are +still considered safe as building blocks for particular constructions, +e.g., there seems to be no known attacks against HMAC-SHA1 or even +HMAC-MD5. In some important cases, use of a ``legacy'' hash function +does not in itself make the application insecure; if a known weakness is +relevant depends on how the hash function is used, and on the threat +model. -The functions are analogous to the MD5 ones. +@subsubsection @acronym{MD5} -@deftp {Context struct} {struct sha256_ctx} +MD5 is a message digest function constructed by Ronald Rivest, and +described in @cite{RFC 1321}. It outputs message digests of 128 bits, or +16 octets. Nettle defines MD5 in @file{}. + +@deftp {Context struct} {struct md5_ctx} @end deftp -@defvr Constant SHA256_DIGEST_SIZE -The size of an SHA256 digest, i.e. 32. +@defvr Constant MD5_DIGEST_SIZE +The size of an MD5 digest, i.e. 16. @end defvr -@defvr Constant SHA256_DATA_SIZE -The internal block size of SHA256. Useful for some special constructions, -in particular HMAC-SHA256. +@defvr Constant MD5_DATA_SIZE +The internal block size of MD5. Useful for some special constructions, +in particular HMAC-MD5. @end defvr -@deftypefun void sha256_init (struct sha256_ctx *@var{ctx}) -Initialize the SHA256 state. +@deftypefun void md5_init (struct md5_ctx *@var{ctx}) +Initialize the MD5 state. @end deftypefun -@deftypefun void sha256_update (struct sha256_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +@deftypefun void md5_update (struct md5_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) Hash some more data. @end deftypefun -@deftypefun void sha256_digest (struct sha256_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) +@deftypefun void md5_digest (struct md5_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{SHA256_DIGEST_SIZE}, in which case only the first @var{length} +@code{MD5_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{sha256_init}. +@code{md5_init}. @end deftypefun -@subsection @acronym{SHA224} +The normal way to use MD5 is to call the functions in order: First +@code{md5_init}, then @code{md5_update} zero or more times, and finally +@code{md5_digest}. After @code{md5_digest}, the context is reset to +its initial state, so you can start over calling @code{md5_update} to +hash new data. -SHA224 is a variant of SHA256, with a different initial state, and with -the output truncated to 224 bits, or 28 octets. Nettle defines SHA224 in -@file{}. +To start over, you can call @code{md5_init} at any time. -The functions are analogous to the MD5 ones. +@subsubsection @acronym{MD2} -@deftp {Context struct} {struct sha224_ctx} +MD2 is another hash function of Ronald Rivest's, described in +@cite{RFC 1319}. It outputs message digests of 128 bits, or 16 octets. +Nettle defines MD2 in @file{}. + +@deftp {Context struct} {struct md2_ctx} @end deftp -@defvr Constant SHA224_DIGEST_SIZE -The size of an SHA224 digest, i.e. 28. +@defvr Constant MD2_DIGEST_SIZE +The size of an MD2 digest, i.e. 16. @end defvr -@defvr Constant SHA224_DATA_SIZE -The internal block size of SHA224. Useful for some special constructions, -in particular HMAC-SHA224. +@defvr Constant MD2_DATA_SIZE +The internal block size of MD2. @end defvr -@deftypefun void sha224_init (struct sha224_ctx *@var{ctx}) -Initialize the SHA224 state. +@deftypefun void md2_init (struct md2_ctx *@var{ctx}) +Initialize the MD2 state. @end deftypefun -@deftypefun void sha224_update (struct sha224_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +@deftypefun void md2_update (struct md2_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) Hash some more data. @end deftypefun -@deftypefun void sha224_digest (struct sha224_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) +@deftypefun void md2_digest (struct md2_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{SHA224_DIGEST_SIZE}, in which case only the first @var{length} +@code{MD2_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{sha224_init}. +@code{md2_init}. @end deftypefun -@subsection @acronym{SHA512} - -SHA512 is a larger sibling to SHA256, with a very similar structure but -with both the output and the internal variables of twice the size. The -internal variables are 64 bits rather than 32, making it significantly -slower on 32-bit computers. It outputs hash values of 512 bits, or 64 -octets. Nettle defines SHA512 in @file{}. +@subsubsection @acronym{MD4} -The functions are analogous to the MD5 ones. +MD4 is a predecessor of MD5, described in @cite{RFC 1320}. Like MD5, it +is constructed by Ronald Rivest. It outputs message digests of 128 bits, +or 16 octets. Nettle defines MD4 in @file{}. Use of MD4 is +not recommended, but it is sometimes needed for compatibility with +existing applications and protocols. -@deftp {Context struct} {struct sha512_ctx} +@deftp {Context struct} {struct md4_ctx} @end deftp -@defvr Constant SHA512_DIGEST_SIZE -The size of an SHA512 digest, i.e. 64. +@defvr Constant MD4_DIGEST_SIZE +The size of an MD4 digest, i.e. 16. @end defvr -@defvr Constant SHA512_DATA_SIZE -The internal block size of SHA512. Useful for some special constructions, -in particular HMAC-SHA512. +@defvr Constant MD4_DATA_SIZE +The internal block size of MD4. @end defvr -@deftypefun void sha512_init (struct sha512_ctx *@var{ctx}) -Initialize the SHA512 state. +@deftypefun void md4_init (struct md4_ctx *@var{ctx}) +Initialize the MD4 state. @end deftypefun -@deftypefun void sha512_update (struct sha512_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +@deftypefun void md4_update (struct md4_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) Hash some more data. @end deftypefun -@deftypefun void sha512_digest (struct sha512_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) +@deftypefun void md4_digest (struct md4_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{SHA512_DIGEST_SIZE}, in which case only the first @var{length} +@code{MD4_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{sha512_init}. +@code{md4_init}. @end deftypefun -@subsection @acronym{SHA384} +@subsubsection @acronym{RIPEMD160} -SHA384 is a variant of SHA512, with a different initial state, and with -the output truncated to 384 bits, or 48 octets. Nettle defines SHA384 in -@file{}. +RIPEMD160 is a hash function designed by Hans Dobbertin, Antoon +Bosselaers, and Bart Preneel, as a strengthened version of RIPEMD +(which, like MD4 and MD5, fails the collision-resistance requirement). +It produces message digests of 160 bits, or 20 octets. Nettle defined +RIPEMD160 in @file{nettle/ripemd160.h}. + +@deftp {Context struct} {struct ripemd160_ctx} +@end deftp + +@defvr Constant RIPEMD160_DIGEST_SIZE +The size of an RIPEMD160 digest, i.e. 20. +@end defvr -The functions are analogous to the MD5 ones. +@defvr Constant RIPEMD160_DATA_SIZE +The internal block size of RIPEMD160. +@end defvr -@deftp {Context struct} {struct sha384_ctx} +@deftypefun void ripemd160_init (struct ripemd160_ctx *@var{ctx}) +Initialize the RIPEMD160 state. +@end deftypefun + +@deftypefun void ripemd160_update (struct ripemd160_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +Hash some more data. +@end deftypefun + +@deftypefun void ripemd160_digest (struct ripemd160_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{RIPEMD160_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{ripemd160_init}. +@end deftypefun + +@subsubsection @acronym{SHA1} + +SHA1 is a hash function specified by @dfn{NIST} (The U.S. National +Institute for Standards and Technology). It outputs hash values of 160 +bits, or 20 octets. Nettle defines SHA1 in @file{} (and +in @file{}, for backwards compatibility). + +@deftp {Context struct} {struct sha1_ctx} @end deftp -@defvr Constant SHA384_DIGEST_SIZE -The size of an SHA384 digest, i.e. 48. +@defvr Constant SHA1_DIGEST_SIZE +The size of an SHA1 digest, i.e. 20. @end defvr -@defvr Constant SHA384_DATA_SIZE -The internal block size of SHA384. Useful for some special constructions, -in particular HMAC-SHA384. +@defvr Constant SHA1_DATA_SIZE +The internal block size of SHA1. Useful for some special constructions, +in particular HMAC-SHA1. @end defvr -@deftypefun void sha384_init (struct sha384_ctx *@var{ctx}) -Initialize the SHA384 state. +@deftypefun void sha1_init (struct sha1_ctx *@var{ctx}) +Initialize the SHA1 state. @end deftypefun -@deftypefun void sha384_update (struct sha384_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) +@deftypefun void sha1_update (struct sha1_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data}) Hash some more data. @end deftypefun -@deftypefun void sha384_digest (struct sha384_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest}) +@deftypefun void sha1_digest (struct sha1_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{SHA384_DIGEST_SIZE}, in which case only the first @var{length} +@code{SHA1_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{sha384_init}. +@code{sha1_init}. @end deftypefun -@subsection @acronym{GOSTHASH94} + +@subsubsection @acronym{GOSTHASH94} The GOST94 or GOST R 34.11-94 hash algorithm is a Soviet-era algorithm used in Russian government standards (see @cite{RFC 4357}). @@ -752,8 +824,9 @@ This function also resets the context in the same way as @code{gosthash94_init}. @end deftypefun - -@subsection @code{struct nettle_hash} +@node nettle_hash abstraction,, Legacy hash functions, Hash functions +@comment node-name, next, previous, up +@subsection The nettle_hash abstraction Nettle includes a struct including information about the supported hash functions. It is defined in @file{}, and is used @@ -777,6 +850,7 @@ The last three attributes are function pointers, of types @deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha256 @deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha384 @deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha512 +@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha3_256 @deftypevrx {Constant Struct} {struct nettle_hash} nettle_gosthash94 These are all the hash functions that Nettle implements. @end deftypevr @@ -2528,7 +2602,7 @@ example if if @var{n_size} is too small, or if @var{e_size} is zero and @node DSA, , RSA, Public-key algorithms @comment node-name, next, previous, up -@subsection Nettle's @acronym{DSA} support +@subsection @acronym{DSA} The @acronym{DSA} digital signature algorithm is more complex than @acronym{RSA}. It was specified during the early 1990s, and in 1994 NIST