CRYPTO_BLAKE2B(3MONOCYPHER)

💖 CRYPTO_BLAKE2B 💖

okay bestie so this is the CRYPTO_BLAKE2B(3MONOCYPHER) page from the LOCAL manual, and it's literally all about cryptographic hashing. no cap. sit down, grab a strawberry 🍓, we're doing this.

---

✨ NAME ✨

crypto_blake2b, crypto_blake2b_general, crypto_blake2b_general_init, crypto_blake2b_init, crypto_blake2b_update, crypto_blake2b_final — cryptographic hashing 🦋

---

✨ SYNOPSIS ✨

#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);

---

🌸 DESCRIPTION 🌸

BLAKE2b is a fast, cryptographically secure hash, and it's built on the ideas of Chacha20. the way it's faster than MD5 but just as secure as SHA-3?? that's giving main character energy, fr fr. 👑

okay but listen, this part matters: BLAKE2b by itself is NOT the move for hashing passwords and deriving keys from them. use the crypto_argon2i(3monocypher) family of functions for that instead. i said what i said. 💅

BLAKE2b is immune to length extension attacks, so it doesn't need any special precautions — like, you don't have to do the whole HMAC algorithm thing. it just handles it. iconic behaviour honestly.

now the arguments, bestie:

• hash — the output hash. that's it, that's the whole thing.
• hash_size — length of hash, in bytes. must be between 1 and 64. anything below 32 is discouraged when you're using Blake2b as a general-purpose hash function; anything below 16 is discouraged when you're using Blake2b as a message authentication code.
• key — some secret key. you cannot predict the final hash without it, periodt. 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're 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.

---

🎀 Direct interface 🎀

the direct interface has two functions: crypto_blake2b() and crypto_blake2b_general(). crypto_blake2b() is there for convenience, and it's equivalent to calling crypto_blake2b_general() with no key and a 64-byte hash. one and done, slay.

with crypto_blake2b_general() you can specify the size of the hash, and you can use a secret key to make the hash unpredictable — which is lowkey exactly what you want for message authentication codes. and here's the cute part: even when you're using a key, you do not have to wipe the context struct with crypto_wipe(3monocypher). 🫶

---

🦋 Incremental interface 🦋

the incremental interface is the one you want for handling streams of data or large files without eating up too much memory. it works in three steps:

1. initialisation with crypto_blake2b_general_init() or crypto_blake2b_init(), which sets up a context with the hashing parameters;
2. update with crypto_blake2b_update(), which hashes the message chunk by chunk and keeps the intermediary result in the context;
3. and finalisation with crypto_blake2b_final(), which produces the final hash. the crypto_blake2b_ctx is automatically wiped upon finalisation. ✨

the invariants of the parameters are the same as for crypto_blake2b_general(). crypto_blake2b_init() is a convenience initialisation function that specifies a 64-byte hash and no key. this is considered a good default. 💅

---

✨ RETURN VALUES ✨

these functions return nothing. void. empty. silent. mysterious. 😭

---

🌈 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(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);

---

💜 SEE ALSO 💜

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

---

⭐ STANDARDS ⭐

these functions implement BLAKE2b, described in RFC 7693. certified. 📜

---

🌸 HISTORY 🌸

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. ancient. vintage. a classic. 👑

---

😭 CAVEATS 😭

Monocypher does not perform any input validation. any deviation from the specified input and output length ranges results in undefined behaviour. bestie, i am begging you, make sure your inputs are correct. fr fr. 💀

---

🔥 SECURITY CONSIDERATIONS 🔥

BLAKE2b is a general-purpose cryptographic hash function. that means it is not suited for hashing passwords and deriving cryptographic keys from passwords in particular. here's why, and stay with me:

cryptographic keys usually have hundreds of bits of entropy, but passwords are often much less complex. when you're storing passwords as hashes or deriving keys from them, the goal is normally to stop attackers from quickly iterating through all possible passwords. and because passwords tend to be simple, it is important to artificially slow attackers down by using especially computationally difficult hashing algorithms. that's the whole vibe check. 💅

Monocypher therefore provides crypto_argon2i(3monocypher) for password hashing and deriving keys from passwords. use that one for passwords, use BLAKE2b for everything else, and we're all good. 🌈

---

and that's the whole page, bestie!! this was the CRYPTO_BLAKE2B(3MONOCYPHER) manual from Debian, dated March 31, 2020. go forth and hash responsibly 💖✨🎀🦋