nettle: Recommended hash functions
1
1 6.1.1 Recommended hash functions
1 --------------------------------
1
1 The following hash functions have no known weaknesses, and are suitable
1 for new applications. The SHA2 family of hash functions were specified
1 by “NIST”, intended as a replacement for SHA1.
1
1 6.1.1.1 SHA256
1 ..............
1
1 SHA256 is a member of the SHA2 family. It outputs hash values of 256
1 bits, or 32 octets. Nettle defines SHA256 in ‘<nettle/sha2.h>’.
1
1 -- Context struct: struct sha256_ctx
1
1 -- Constant: SHA256_DIGEST_SIZE
1 The size of a SHA256 digest, i.e. 32.
1
1 -- Constant: SHA256_BLOCK_SIZE
1 The internal block size of SHA256. Useful for some special
1 constructions, in particular HMAC-SHA256.
1
1 -- Function: void sha256_init (struct sha256_ctx *CTX)
1 Initialize the SHA256 state.
1
1 -- Function: void sha256_update (struct sha256_ctx *CTX, size_t LENGTH,
1 const uint8_t *DATA)
1 Hash some more data.
1
1 -- Function: void sha256_digest (struct sha256_ctx *CTX, size_t LENGTH,
1 uint8_t *DIGEST)
1 Performs final processing and extracts the message digest, writing
1 it to DIGEST. LENGTH may be smaller than ‘SHA256_DIGEST_SIZE’, in
1 which case only the first LENGTH octets of the digest are written.
1
1 This function also resets the context in the same way as
1 ‘sha256_init’.
1
1 Earlier versions of nettle defined SHA256 in the header file
1 ‘<nettle/sha.h>’, which is now deprecated, but kept for compatibility.
1
1 6.1.1.2 SHA224
1 ..............
1
1 SHA224 is a variant of SHA256, with a different initial state, and with
1 the output truncated to 224 bits, or 28 octets. Nettle defines SHA224
1 in ‘<nettle/sha2.h>’ (and in ‘<nettle/sha.h>’, for backwards
1 compatibility).
1
1 -- Context struct: struct sha224_ctx
1
1 -- Constant: SHA224_DIGEST_SIZE
1 The size of a SHA224 digest, i.e. 28.
1
1 -- Constant: SHA224_BLOCK_SIZE
1 The internal block size of SHA224. Useful for some special
1 constructions, in particular HMAC-SHA224.
1
1 -- Function: void sha224_init (struct sha224_ctx *CTX)
1 Initialize the SHA224 state.
1
1 -- Function: void sha224_update (struct sha224_ctx *CTX, size_t LENGTH,
1 const uint8_t *DATA)
1 Hash some more data.
1
1 -- Function: void sha224_digest (struct sha224_ctx *CTX, size_t LENGTH,
1 uint8_t *DIGEST)
1 Performs final processing and extracts the message digest, writing
1 it to DIGEST. LENGTH may be smaller than ‘SHA224_DIGEST_SIZE’, in
1 which case only the first LENGTH octets of the digest are written.
1
1 This function also resets the context in the same way as
1 ‘sha224_init’.
1
1 6.1.1.3 SHA512
1 ..............
1
1 SHA512 is a larger sibling to SHA256, with a very similar structure but
1 with both the output and the internal variables of twice the size. The
1 internal variables are 64 bits rather than 32, making it significantly
1 slower on 32-bit computers. It outputs hash values of 512 bits, or 64
1 octets. Nettle defines SHA512 in ‘<nettle/sha2.h>’ (and in
1 ‘<nettle/sha.h>’, for backwards compatibility).
1
1 -- Context struct: struct sha512_ctx
1
1 -- Constant: SHA512_DIGEST_SIZE
1 The size of a SHA512 digest, i.e. 64.
1
1 -- Constant: SHA512_BLOCK_SIZE
1 The internal block size of SHA512, 128. Useful for some special
1 constructions, in particular HMAC-SHA512.
1
1 -- Function: void sha512_init (struct sha512_ctx *CTX)
1 Initialize the SHA512 state.
1
1 -- Function: void sha512_update (struct sha512_ctx *CTX, size_t LENGTH,
1 const uint8_t *DATA)
1 Hash some more data.
1
1 -- Function: void sha512_digest (struct sha512_ctx *CTX, size_t LENGTH,
1 uint8_t *DIGEST)
1 Performs final processing and extracts the message digest, writing
1 it to DIGEST. LENGTH may be smaller than ‘SHA512_DIGEST_SIZE’, in
1 which case only the first LENGTH octets of the digest are written.
1
1 This function also resets the context in the same way as
1 ‘sha512_init’.
1
1 6.1.1.4 SHA384 and other variants of SHA512
1 ...........................................
1
1 Several variants of SHA512 have been defined, with a different initial
1 state, and with the output truncated to shorter length than 512 bits.
1 Naming is a bit confused, these algorithms are called SHA512-224,
1 SHA512-256 and SHA384, for output sizes of 224, 256 and 384 bits,
1 respectively. Nettle defines these in ‘<nettle/sha2.h>’ (and in
1 ‘<nettle/sha.h>’, for backwards compatibility).
1
1 -- Context struct: struct sha512_224_ctx
1 -- Context struct: struct sha512_256_ctx
1 -- Context struct: struct sha384_ctx
1 These context structs are all the same as sha512_ctx. They are
1 defined as simple preprocessor aliases, which may cause some
1 problems if used as identifiers for other purposes. So avoid doing
1 that.
1
1 -- Constant: SHA512_224_DIGEST_SIZE
1 -- Constant: SHA512_256_DIGEST_SIZE
1 -- Constant: SHA384_DIGEST_SIZE
1 The digest size for each variant, i.e., 28, 32, and 48,
1 respectively.
1
1 -- Constant: SHA512_224_BLOCK_SIZE
1 -- Constant: SHA512_256_BLOCK_SIZE
1 -- Constant: SHA384_BLOCK_SIZE
1 The internal block size, same as SHA512_BLOCK_SIZE, i.e., 128.
1 Useful for some special constructions, in particular HMAC-SHA384.
1
1 -- Function: void sha512_224_init (struct sha512_224_ctx *CTX)
1 -- Function: void sha512_256_init (struct sha512_256_ctx *CTX)
1 -- Function: void sha384_init (struct sha384_ctx *CTX)
1 Initialize the context struct.
1
1 -- Function: void sha512_224_update (struct sha512_224_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 -- Function: void sha512_256_update (struct sha512_256_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 -- Function: void sha384_update (struct sha384_ctx *CTX, size_t LENGTH,
1 const uint8_t *DATA)
1 Hash some more data. These are all aliases for sha512_update,
1 which does the same thing.
1
1 -- Function: void sha512_224_digest (struct sha512_224_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 -- Function: void sha512_256_digest (struct sha512_256_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 -- Function: void sha384_digest (struct sha384_ctx *CTX, size_t LENGTH,
1 uint8_t *DIGEST)
1 Performs final processing and extracts the message digest, writing
1 it to DIGEST. LENGTH may be smaller than the specified digest
1 size, in which case only the first LENGTH octets of the digest are
1 written.
1
1 These function also reset the context in the same way as the
1 corresponding init function.
1
1 6.1.1.5 SHA3-224
1 ................
1
1 The SHA3 hash functions were specified by NIST in response to weaknesses
1 in SHA1, and doubts about SHA2 hash functions which structurally are
1 very similar to SHA1. SHA3 is a result of a competition, where the
1 winner, also known as Keccak, was designed by Guido Bertoni, Joan
1 Daemen, Michaël Peeters and Gilles Van Assche. It is structurally very
1 different from all widely used earlier hash functions. Like SHA2, there
1 are several variants, with output sizes of 224, 256, 384 and 512 bits
1 (28, 32, 48 and 64 octets, respectively). In August 2015, it was
1 formally standardized by NIST, as FIPS 202,
1 <http://dx.doi.org/10.6028/NIST.FIPS.202>.
1
1 Note that the SHA3 implementation in earlier versions of Nettle was
1 based on the specification at the time Keccak was announced as the
1 winner of the competition, which is incompatible with the final standard
1 and hence with current versions of Nettle. The ‘nette/sha3.h’ defines a
1 preprocessor symbol ‘NETTLE_SHA3_FIPS202’ to indicate conformance with
1 the standard.
1
1 -- Constant: NETTLE_SHA3_FIPS202
1 Defined to 1 in Nettle versions supporting FIPS 202. Undefined in
1 earlier versions.
1
1 Nettle defines SHA3-224 in ‘<nettle/sha3.h>’.
1
1 -- Context struct: struct sha3_224_ctx
1
1 -- Constant: SHA3_224_DIGEST_SIZE
1 The size of a SHA3_224 digest, i.e., 28.
1
1 -- Constant: SHA3_224_BLOCK_SIZE
1 The internal block size of SHA3_224.
1
1 -- Function: void sha3_224_init (struct sha3_224_ctx *CTX)
1 Initialize the SHA3-224 state.
1
1 -- Function: void sha3_224_update (struct sha3_224_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 Hash some more data.
1
1 -- Function: void sha3_224_digest (struct sha3_224_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 Performs final processing and extracts the message digest, writing
1 it to DIGEST. LENGTH may be smaller than ‘SHA3_224_DIGEST_SIZE’,
1 in which case only the first LENGTH octets of the digest are
1 written.
1
1 This function also resets the context.
1
1 6.1.1.6 SHA3-256
1 ................
1
1 This is SHA3 with 256-bit output size, and possibly the most useful of
1 the SHA3 hash functions.
1
1 Nettle defines SHA3-256 in ‘<nettle/sha3.h>’.
1
1 -- Context struct: struct sha3_256_ctx
1
1 -- Constant: SHA3_256_DIGEST_SIZE
1 The size of a SHA3_256 digest, i.e., 32.
1
1 -- Constant: SHA3_256_BLOCK_SIZE
1 The internal block size of SHA3_256.
1
1 -- Function: void sha3_256_init (struct sha3_256_ctx *CTX)
1 Initialize the SHA3-256 state.
1
1 -- Function: void sha3_256_update (struct sha3_256_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 Hash some more data.
1
1 -- Function: void sha3_256_digest (struct sha3_256_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 Performs final processing and extracts the message digest, writing
1 it to DIGEST. LENGTH may be smaller than ‘SHA3_256_DIGEST_SIZE’,
1 in which case only the first LENGTH octets of the digest are
1 written.
1
1 This function also resets the context.
1
1 6.1.1.7 SHA3-384
1 ................
1
1 This is SHA3 with 384-bit output size.
1
1 Nettle defines SHA3-384 in ‘<nettle/sha3.h>’.
1
1 -- Context struct: struct sha3_384_ctx
1
1 -- Constant: SHA3_384_DIGEST_SIZE
1 The size of a SHA3_384 digest, i.e., 48.
1
1 -- Constant: SHA3_384_BLOCK_SIZE
1 The internal block size of SHA3_384.
1
1 -- Function: void sha3_384_init (struct sha3_384_ctx *CTX)
1 Initialize the SHA3-384 state.
1
1 -- Function: void sha3_384_update (struct sha3_384_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 Hash some more data.
1
1 -- Function: void sha3_384_digest (struct sha3_384_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 Performs final processing and extracts the message digest, writing
1 it to DIGEST. LENGTH may be smaller than ‘SHA3_384_DIGEST_SIZE’,
1 in which case only the first LENGTH octets of the digest are
1 written.
1
1 This function also resets the context.
1
1 6.1.1.8 SHA3-512
1 ................
1
1 This is SHA3 with 512-bit output size.
1
1 Nettle defines SHA3-512 in ‘<nettle/sha3.h>’.
1
1 -- Context struct: struct sha3_512_ctx
1
1 -- Constant: SHA3_512_DIGEST_SIZE
1 The size of a SHA3_512 digest, i.e. 64.
1
1 -- Constant: SHA3_512_BLOCK_SIZE
1 The internal block size of SHA3_512.
1
1 -- Function: void sha3_512_init (struct sha3_512_ctx *CTX)
1 Initialize the SHA3-512 state.
1
1 -- Function: void sha3_512_update (struct sha3_512_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 Hash some more data.
1
1 -- Function: void sha3_512_digest (struct sha3_512_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 Performs final processing and extracts the message digest, writing
1 it to DIGEST. LENGTH may be smaller than ‘SHA3_512_DIGEST_SIZE’,
1 in which case only the first LENGTH octets of the digest are
1 written.
1
1 This function also resets the context.
1