Boring crypto that simply works

cryptographic hash-based message authentication code with SHA-512

#include <monocypher-ed25519.h>

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

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

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

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

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:

The output MAC, which is always 64-bytes long.
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.
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.
The message to compute the HMAC for. May overlap with hmac. May be NULL if message_size is 0.
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 (), which sets up a context with the hashing parameters;
  • update with (), which hashes the message chunk by chunk and keeps the intermediary result in the context;
  • and finalisation with (), which produces the final hash. The crypto_hmac_sha512_ctx is automatically wiped upon finalisation.

() 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 compare (possibly truncated) MACs.

These functions return nothing.

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             */
uint8_t key    [32];                /* Key                     */
uint8_t message[10] = "Lorem ipsu"; /* Message to authenticate */
arc4random_buf(key, 32);
crypto_hmac_sha512(hash, key, 32, message, 10);
/* Wipe secrets if they are no longer needed */
crypto_wipe(message, 10);
crypto_wipe(key, 32);

Computing a message authentication code incrementally:

uint8_t hash   [64];        /* Output hash             */
uint8_t key    [32];        /* Key                     */
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);

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

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.

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 Debian