crypto_blake2b.3monocypher - Man Page

#include <monocypher.h>

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

void
crypto_blake2b_general(uint8_t *hash, size_t hash_size, const uint8_t *key, size_t key_size, const uint8_t *message, size_t message_size);

void
crypto_blake2b_init(crypto_blake2b_ctx *ctx);

void
crypto_blake2b_general_init(crypto_blake2b_ctx *ctx, size_t hash_size, const uint8_t *key, size_t key_size);

void
crypto_blake2b_update(crypto_blake2b_ctx *ctx, const uint8_t *message, size_t message_size);

void
crypto_blake2b_final(crypto_blake2b_ctx *ctx, uint8_t *hash);

BLAKE2b is a fast cryptographically secure hash, based on the ideas of Chacha20. It is faster than MD5, yet just as secure as SHA-3.

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

BLAKE2b is immune to length extension attacks, and as such does not require any specific precautions, such as using the HMAC algorithm.

The arguments are:

hash

The output hash.

hash_size

Length of hash, in bytes. Must be between 1 and 64. Anything below 32 is discouraged when using Blake2b as a general-purpose hash function; anything below 16 is discouraged when using Blake2b as a message authentication code.

key

Some secret key. One cannot predict the final hash without it. May be NULL if key_size is 0, in which case no key is used. Keys can be used to create a message authentication code (MAC). Use crypto_verify16(3monocypher), crypto_verify32(3monocypher), or crypto_verify64(3monocypher) to compare MACs created this way. Choose the size of the hash accordingly. Users may want to wipe the key with crypto_wipe(3monocypher) once they are done with it.

key_size

Length of key, in bytes. Must be between 0 and 64. 32 is a good default.

message

The message to hash. May overlap with hash. May be NULL if message_size is 0.

message_size

Length of message, in bytes.

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(3monocypher) for advice about how to generate cryptographically secure random bytes.

Hashing a message all at once:

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

Computing a message authentication code all at once:

uint8_t hash   [16];
uint8_t key    [32];
uint8_t message[11] = "Lorem ipsu"; /* Message to authenticate */
arc4random_buf(key, 32);
crypto_blake2b_general(hash, 16, key, 32, message, 11);
/* Wipe secrets if they are no longer needed */
crypto_wipe(message, 11);
crypto_wipe(key, 32);

Hashing a message incrementally (without a key):

uint8_t hash   [ 64]; /* Output hash (64 bytes) */
uint8_t message[500] = {1}; /* Message to hash  */
crypto_blake2b_ctx ctx;
crypto_blake2b_init(&ctx);
for (size_t i = 0; i < 500; i += 100) {
    crypto_blake2b_update(&ctx, message + i, 100);
}
crypto_blake2b_final(&ctx, hash);

Computing a message authentication code incrementally:

uint8_t hash   [ 16];
uint8_t key    [ 32];
uint8_t message[500] = {1}; /* Message to authenticate         */
crypto_blake2b_ctx ctx;
arc4random_buf(key, 32);
crypto_blake2b_general_init(&ctx, 16, key, 32);
/* Wipe the key */
crypto_wipe(key, 32);
for (size_t i = 0; i < 500; i += 100) {
    crypto_blake2b_update(&ctx, message + i, 100);
    /* Wipe secrets if they are no longer needed */
    crypto_wipe(message + i, 100);
}
crypto_blake2b_final(&ctx, hash);

crypto_key_exchange(3monocypher), crypto_lock(3monocypher), intro(3monocypher)

These functions implement BLAKE2b, described in RFC 7693.

The crypto_blake2b(), crypto_blake2b_general(), crypto_blake2b_general_init(), crypto_blake2b_init(), crypto_blake2b_update(), and crypto_blake2b_final() functions first appeared in Monocypher 0.1.

Monocypher does not perform any input validation. Any deviation from the specified input and output length ranges results in undefined behaviour. Make sure your inputs are correct.

BLAKE2b 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(3monocypher) for password hashing and deriving keys from passwords.

The man pages crypto_blake2b_final.3monocypher(3), crypto_blake2b_general.3monocypher(3), crypto_blake2b_general_init.3monocypher(3), crypto_blake2b_init.3monocypher(3) and crypto_blake2b_update.3monocypher(3) are aliases of crypto_blake2b.3monocypher(3).