CRYPTO_BLAKE2B(3MONOCYPHER)

CRYPTO_BLAKE2B(3MONOCYPHER) | 3MONOCYPHER | CRYPTO_BLAKE2B(3MONOCYPHER)

# NAME

`crypto_blake2b`, `crypto_blake2b_keyed`, `crypto_blake2b_init`, `crypto_blake2b_keyed_init`, `crypto_blake2b_update`, `crypto_blake2b_final` — hashing, message authentication, and key derivation with BLAKE2b

# SYNOPSIS

`#include <monocypher.h>`

void
`crypto_blake2b`(uint8_t *hash, size_t hash_size, const uint8_t *message, size_t message_size);

`crypto_blake2b_keyed`(uint8_t *hash, size_t hash_size, uint8_t *key, 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, 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(3monocypher) 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(3monocypher), crypto_verify32(3monocypher), or crypto_verify64(3monocypher) 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(3monocypher) 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(3monocypher). Passwords do not contain enough entropy to be used as input key material. Hash them with crypto_argon2(3monocypher) 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(3monocypher) 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(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, 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;
    		}
    	}
    }

# SEE ALSO

crypto_x25519(3monocypher), crypto_aead_lock(3monocypher), intro(3monocypher)

# 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(3monocypher) 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