CRYPTO_BLAKE2B(3MONOCYPHER)

3MONOCYPHER

CRYPTO_BLAKE2B(3MONOCYPHER)

NAME

hashing, message authentication, and key derivation with BLAKE2b

SYNOPSIS

#include <monocypher.h>

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

crypto_blake2b_keyed(uint8_t hash[64], size_t hash_size, uint8_t key[64], size_t key_size, const uint8_t *message, size_t message_size);

void
crypto_blake2b_init(crypto_blake2b_ctx *ctx, size_t hash_size);

void
crypto_blake2b_keyed_init(crypto_blake2b_ctx *ctx, size_t hash_size, uint8_t key[64], 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

Hashing

crypto_blake2b(), crypto_blake2b_init(), crypto_blake2b_update(), and crypto_blake2b_final() implement BLAKE2b, a 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_argon2() family of functions for that purpose instead.

While BLAKE2b is immune to length extension attacks, and as such requires fewer precautions than older hashes, we do recommend avoiding prefix-MAC and using keyed mode with crypto_blake2b_keyed() instead. Doing so enables better security arguments when using BLAKE2b as a random oracle.

The arguments are:

config: The configuration parameter structure, see below.
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.
message: The message to hash. May overlap with hash. May be NULL if message_size is 0.
message_size: Length of message, in bytes.

Message authentication codes

crypto_blake2b_keyed(), crypto_blake2b_keyed_init(), crypto_blake2b_update(), and crypto_blake2b_final() implement keyed BLAKE2b, and can be used for message authentication codes or as a random oracle, just like HMAC. The arguments are:

hash: The output message authentication code (MAC). To avoid timing attacks, use crypto_verify16(), crypto_verify32(), or crypto_verify64() to compare (possibly truncated) MACs.
hash_size: Length of hash, in bytes. Must be between 1 and 64. Anything below 16 is discouraged when using BLAKE2b as a message authentication code. Anything below 32 is discouraged when using BLAKE2b as a key derivation function (KDF).
key: Some secret key. When uniformly random, one cannot predict the final hash without it. Users may want to wipe the key with crypto_wipe() once they are done with it. May overlap with hash or message. May be NULL if key_size is 0, in which case no key is used. Can also be used as a random salt in the context of KDF extraction, or as pre-shared-key in the context of KDF expansion.
key_size: Length of key, in bytes. Must be between 0 and 64. 32 is a good default.
message: The message to compute the MAC for. May overlap with hash or key. May be NULL if message_size is 0. Can also be used as input key material in the context of KDF extraction, or to host a counter and domain separation string in the context of KDF expansion.
message_size: Length of message, in bytes.

Key derivation

BLAKE2b can be used to implement “key derivation functions” (KDF) very similar to HKDF. The typical parameters of a KDF are:

IKM: Input key material containing enough secret entropy to derive uniformly random keys from, such as the shared secret of a key exchange performed with crypto_x25519(). Passwords do not contain enough entropy to be used as input key material. Hash them with crypto_argon2() instead.
salt: An optional random salt, used to increase the security of the output key material (OKM) in some settings. It should be either absent, constant, or contain at least 16 random bytes.
info: Optional domain separation string for key derivation.

From these parameters, the KDF derives an arbitrary amount of independent random bytes, also called “output key material” (OKM), that can be used as regular encryption or secret keys.

In practice, KDFs are often separated in two steps: “extraction” and “expansion”. The extraction step reads the IKM (and optional salt) to derive a “pseudo-random key” (PRK), which can be used either directly as a regular key, or as an input for the extraction step. The expansion step then reads the PRK (and optional info) to make the OKM.

To implement KDF extraction, just call crypto_blake2b_keyed() with the message as the IKM and key as the salt, or crypto_blake2b() if there is no salt. This is unintuitive, but having the IKM in the message argument lets us input arbitrary amounts of data. It is also the HMAC and HKDF way.

For KDF expansion any pseudo-random-function (PRF) can be used. You can call crypto_blake2b_keyed() in counter mode with key as the PRK (though doing it manually is a bit tedious), or crypto_chacha20_djb() with its key as the PRK and its nonce for domain separation.

Incremental interface

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_blake2b_init() or crypto_blake2b_keyed_init(), which set up a context with the hashing parameters;
Update with crypto_blake2b_update(), which hashes the message chunk by chunk and keeps the intermediary result in the context;
and Finalisation with crypto_blake2b_final(), which produces the final hash. The crypto_blake2b_ctx is automatically wiped upon finalisation.

Calling crypto_blake2b() is the same as calling crypto_blake2b_init(), crypto_blake2b_update(), and crypto_blake2b_final(). Calling crypto_blake2b_keyed() is the same as calling crypto_blake2b_keyed_init(), crypto_blake2b_update(), and crypto_blake2b_final().

Calling crypto_blake2b() is the same as calling crypto_blake2b_keyed() with an empty key.

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.

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, sizeof(hash), message, sizeof(message));

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, sizeof(key));
crypto_blake2b_keyed(hash   , sizeof(hash),
                     key    , sizeof(key),
                     message, sizeof(message));
/* Wipe secrets if they are no longer needed */
crypto_wipe(message, sizeof(message));
crypto_wipe(key,     sizeof(key));

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, sizeof(hash));
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 */
arc4random_buf(key, sizeof(key));
crypto_blake2b_ctx ctx;
crypto_blake2b_keyed_init(&ctx, sizeof(hash), key,
                          sizeof(key));
/* Wipe the key */
crypto_wipe(key, sizeof(key));
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);

Computing key derivation with BLAKE2b and ChaCha20:

void kdf(uint8_t *okm,  size_t okm_size,  /* unlimited   */
         uint8_t *ikm,  size_t ikm_size,  /* unlimited   */
         uint8_t *salt, size_t salt_size, /* <= 64 bytes */
         uint8_t info[8])                 /* ==  8 bytes */
{
	/* Extract */
	uint8_t prk[32];
	crypto_blake2b_keyed(prk , sizeof(prk),
	                     salt, salt_size,
	                     ikm , ikm_size);
	/* Expand */
	crypto_chacha20_djb(okm, NULL, okm_size, prk, info, 0);
}

Computing key derivation with BLAKE2b and XChaCha20:

void xkdf(uint8_t *okm,  size_t okm_size,  /* unlimited   */
          uint8_t *ikm,  size_t ikm_size,  /* unlimited   */
          uint8_t *salt, size_t salt_size, /* <= 64 bytes */
          uint8_t *info, size_t info_size) /* unlimited   */
{
	/* Extract */
	uint8_t prk[32];
	crypto_blake2b_keyed(prk , sizeof(prk),
	                     salt, salt_size,
	                     ikm , ikm_size);
	/* Expand */
	uint8_t nonce[24];
	crypto_blake2b(nonce, sizeof(nonce), info, info_size);
	crypto_chacha20_x(okm, NULL, okm_size, prk, nonce, 0);
}

Computing key derivation with BLAKE2b alone (a little tedious indeed):

#define MIN(a, b) ((a) < (b) ? (a) : (b))

void b2kdf(uint8_t *okm,  size_t okm_size,  /* unlimited   */
           uint8_t *ikm,  size_t ikm_size,  /* unlimited   */
           uint8_t *salt, size_t salt_size, /* <= 64 bytes */
           uint8_t *info, size_t info_size) /* unlimited   */
{
	/* Extract */
	uint8_t prk[64];
	crypto_blake2b_keyed(prk , sizeof(prk),
	                     salt, salt_size,
	                     ikm , ikm_size);
	/* Expand */
	uint8_t ctr[8] = {0};
	while(okm_size > 0) {
		size_t size = MIN(okm_size, 64);
		crypto_blake2b_ctx ctx;
		crypto_blake2b_keyed_init(&ctx, size, prk, 64);
		crypto_blake2b_update(&ctx, ctr, sizeof(ctr));
		crypto_blake2b_update(&ctx, info, info_size);
		crypto_blake2b_final(&ctx, okm);
		okm      += size;
		okm_size -= size;
		/* increment ctr */
		unsigned acc = 1;
		for (size_t i = 0; i < sizeof(ctr); i++) {
			acc    = ctr[i] + acc;
			ctr[i] = acc & 0xff;
			acc  >>= 8;
		}
	}
}

STANDARDS

These functions implement BLAKE2b, described in RFC 7693.

HISTORY

The crypto_blake2b(), crypto_blake2b_init(), crypto_blake2b_update(), and crypto_blake2b_final() functions first appeared in Monocypher 0.1. In Monocypher 4.0.0, crypto_blake2b_general() and crypto_blake2b_general_init() were removed, crypto_blake2b_keyed() and crypto_blake2b_keyed_init() were added, and the hash_size argument were added to crypto_blake2b() and crypto_blake2b_init().

CAVEATS

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.

SECURITY CONSIDERATIONS

BLAKE2b is a general-purpose cryptographic hash function; this means that it is not suited for hashing passwords and deriving cryptographic keys from passwords. 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 computationally difficult hashing algorithms. Monocypher therefore provides crypto_argon2() for password hashing and deriving keys from passwords.

IMPLEMENTATION DETAILS

The core loop is unrolled by default. This speeds up BLAKE2b by about 20% on modern processors. On the other hand, this inflates the binary size by several kilobytes, and is slower on some embedded platforms. To roll the loop and generate a smaller binary, compile Monocypher with the -DBLAKE2_NO_UNROLLING option.

February 2, 2023

Debian