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 keeps 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 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 */ 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);
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.
March 2, 2020 | Debian |