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

Reorganization of hash function documentation. Document sha3-256.

parent c24dda8e
2012-12-03 Niels Möller <nisse@lysator.liu.se>
* 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 <nisse@lysator.liu.se>
Split sha.h into new files sha1.h and sha2.h. Replaced all
......
......@@ -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{<nettle/md5.h>}.
@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{<nettle/sha2.h>}.
@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{<nettle/sha.h>}, 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{<nettle/md2.h>}.
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{<nettle/sha2.h>} (and in @file{<nettle/sha.h>}, 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{<nettle/md4.h>}. 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{<nettle/sha2.h>} (and in
@file{<nettle/sha.h>}, 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{<nettle/sha2.h>} (and in @file{<nettle/sha.h>}, 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{<nettle/sha.h>}.
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{<nettle/sha3.h>}.
@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{<nettle/sha.h>}.
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{<nettle/md5.h>}.
@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{<nettle/sha.h>}.
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{<nettle/md2.h>}.
@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{<nettle/sha.h>}.
@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{<nettle/md4.h>}. 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{<nettle/sha.h>}.
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{<nettle/sha1.h>} (and
in @file{<nettle/sha.h>}, 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{<nettle/nettle-meta.h>}, 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
......