Monocypher

Boring crypto that simply works
CRYPTO_HMAC_SHA512(3MONOCYPHER) 3MONOCYPHER CRYPTO_HMAC_SHA512(3MONOCYPHER)

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

Computing a message authentication code all at once:
uint8_t hash   [ 64]; /* Output hash  (between 1 and 64 bytes) */ 
uint8_t key    [ 32]; /* Optional key (between 0 and 64 bytes) */ 
uint8_t message[500]; /* Message to hash                       */ 
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]; /* Optional key (between 0 and 64 bytes) */ 
uint8_t message[500]; /* Message to hash                       */ 
crypto_hmac_sha512_ctx ctx; 
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);

SEE ALSO

crypto_blake2b(), crypto_lock(), crypto_poly1305(), crypto_sha512(), intro()

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.
December 12, 2019 Linux 4.15.0-88-generic