NAME

cryptographic hashing with the SHA-512 algorithm #include <monocypher-ed25519.h>

void
crypto_sha512(uint8_t hash[64], const uint8_t *message, size_t message_size);

void
crypto_sha512_init(crypto_sha512_ctx *ctx);

void
crypto_sha512_update(crypto_sha512_ctx *ctx, const uint8_t *message, size_t message_size);

void
crypto_sha512_final(crypto_sha512_ctx *ctx, uint8_t hash[64]);

DESCRIPTION

SHA-512 is a cryptographically secure hash, provided to enable compatibility with other cryptographic systems. It is generally recommended to use crypto_blake2b() instead, as it both performs faster on x86_64 CPUs and lacks many of the pitfalls of SHA-512.

Note that SHA-512 itself is not suitable for hashing passwords and deriving keys from them; use the crypto_argon2i() family of functions for that purpose instead.

SHA-512 is vulnerable to length extension attacks; using it as a message authentication code (MAC) algorithm or keyed hash requires precautions. The crypto_hmac_sha512() family of functions provides HMAC with SHA-512. Use crypto_verify64() to compare MACs created this way.

The arguments are:

hash: The output hash, which is always 64 bytes long.
message: The message to hash. May overlap with hash. May be NULL if message_size is 0.
message_size: Length of message, in bytes.

An incremental interface is provided. It is useful for handling streams of data or large files without using too much memory. This interface uses three steps:

initialisation with crypto_sha512_init(), which sets up a context with the hashing parameters;
update with crypto_sha512_update(), which hashes the message chunk by chunk, and keep the intermediary result in the context;
and finalisation with crypto_sha512_final(), which produces the final hash. The crypto_sha512_ctx is automatically wiped upon finalisation.

crypto_sha512() is a convenience function that performs crypto_sha512_init(), crypto_sha512_update(), and crypto_sha512_final().

RETURN VALUES

These functions return nothing.

EXAMPLES

Hashing a message all at once:

uint8_t hash   [64]; /* Output hash (64 bytes)          */ 
uint8_t message[12] = "Lorem ipsum"; /* Message to hash */ 
crypto_sha512(hash, message, 12);

Hashing a message incrementally:

uint8_t hash   [ 64]; /* Output hash (64 bytes) */ 
uint8_t message[500] = {1}; /* Message to hash  */ 
crypto_sha512_ctx ctx; 
crypto_sha512_init(&ctx); 
for (size_t i = 0; i < 500; i += 100) { 
    crypto_sha512_update(&ctx, message + i, 100); 
} 
crypto_sha512_final(&ctx, hash);

STANDARDS

These functions implement SHA-512, described in RFC 6234 and the Federal Information Processing Standard (FIPS) 180-4.

HISTORY

The crypto_sha512(), crypto_sha512_init(), crypto_sha512_update(), and crypto_sha512_final() functions first appeared in Monocypher 0.3; they were not intended for use outside Monocypher itself and thus undocumented. They became part of the official API in Monocypher 3.0.0.

SECURITY CONSIDERATIONS

SHA-512 is a general-purpose cryptographic hash function; this means that it is not suited for hashing passwords and deriving cryptographic keys from passwords in particular. While cryptographic keys usually have hundreds of bits of entropy, passwords are often much less complex. When storing passwords as hashes or when deriving keys from them, the goal is normally to prevent attackers from quickly iterating all possible passwords. Because passwords tend to be simple, it is important to artificially slow down attackers by using especially computationally difficult hashing algorithms. Monocypher therefore provides crypto_argon2i() for password hashing and deriving keys from passwords.

February 5, 2020

Linux 4.15.0-46-generic