NAME

cryptographic hash-based message authentication code with SHA-512 #include <monocypher-ed25519.h>

void
crypto_hmac_sha512(uint8_t hmac[64], const uint8_t *key, size_t key_size, const uint8_t *message, size_t message_size);

void
crypto_hmac_sha512_init(crypto_hmac_sha512_ctx *ctx, const uint8_t *key, size_t key_size);

void
crypto_hmac_sha512_update(crypto_hmac_sha512_ctx *ctx, const uint8_t *message, size_t message_size);

void
crypto_hmac_sha512_final(crypto_hmac_sha512_ctx *ctx, uint8_t hmac[64]);

DESCRIPTION

HMAC with SHA-512 is a cryptographically secure message authentication code (MAC), provided to enable compatibility with other cryptographic systems. It is generally recommended to use crypto_blake2b_general() instead, as it performs faster on x86_64 CPUs.

The arguments are:

hmac: The output MAC, which is always 64 bytes long.
key: Some secret key. One cannot predict the final hash without it. Users may want to wipe the key with crypto_wipe() once they are done with it.
key_size: Length of key, in bytes. 32 is a good default. Keys longer than 128 bytes will be reduced to 64 bytes by hashing the key with SHA-512.
message: The message to compute the HMAC for. May overlap with hmac. 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_hmac_sha512_init(), which sets up a context with the hashing parameters;
update with crypto_hmac_sha512_update(), which hashes the message chunk by chunk, and keep the intermediary result in the context;
and finalisation with crypto_hmac_sha512_final(), which produces the final hash. The crypto_hmac_sha512_ctx is automatically wiped upon finalisation.

crypto_hmac_sha512() is a convenience function that performs crypto_hmac_sha512_init(), crypto_hmac_sha512_update(), and crypto_hmac_sha512_final().

MACs may be truncated safely down to at most 16 bytes; the crypto_verify64(), crypto_verify32(), and crypto_verify16() functions can be used to to compare (possibly truncated) MACs.

RETURN VALUES

These functions return nothing.

EXAMPLES

The following examples assume the existence of arc4random_buf(), which fills the given buffer with cryptographically secure random bytes. If arc4random_buf() does not exist on your system, see intro() for advice about how to generate cryptographically secure random bytes.

Computing a message authentication code all at once:

uint8_t hash   [64]; /* Output hash  (between 1 and 64 bytes)  */ 
uint8_t key    [32]; /* Key          (at least 1 byte)         */ 
uint8_t message[10] = "Lorem ipsu"; /* Message to authenticate */ 
arc4random_buf(key, 32); 
crypto_hmac_sha512(hash, key, 32, message, 500); 
/* Wipe secrets if they are no longer needed */ 
crypto_wipe(message, 500); 
crypto_wipe(key, 32);

Computing a message authentication code incrementally:

uint8_t hash   [64]; /* Output hash  (between 1 and 64 bytes)  */ 
uint8_t key    [32]; /* Key          (at least 1 byte)         */ 
uint8_t message[500] = {1}; /* Message to authenticate         */ 
crypto_hmac_sha512_ctx ctx; 
arc4random_buf(key, 32); 
crypto_hmac_sha512_init(&ctx, key, 32); 
/* Wipe the key */ 
crypto_wipe(key, 32); 
for (size_t i = 0; i < 500; i += 100) { 
    crypto_hmac_sha512_update(&ctx, message + i, 100); 
    /* Wipe secrets if they are no longer needed */ 
    crypto_wipe(message + i, 100); 
} 
crypto_hmac_sha512_final(&ctx, hash);

STANDARDS

These functions implement HMAC with SHA-512. HMAC and SHA-512 itself are described in RFC 6234; SHA-512 is also described in the Federal Information Processing Standard (FIPS) 180-4; HMAC is also described in FIPS 198-1.

HISTORY

The crypto_hmac_sha512(), crypto_hmac_sha512_init(), crypto_hmac_sha512_update(), and crypto_hmac_sha512_final() functions first appeared in Monocypher 3.0.0.

March 2, 2020