Hashing

Purpose

BLAKE2b is a cryptographic hash function. It takes a message of any size and produces a 128-bit to 512-bit hash.

This hash acts as a fingerprint for the data. Hashes can be used to uniquely identify messages, detect corruption, detect duplicate data, and index data in a hash table.

It is also possible to personalize the output for your application/a specific use case via a constant and to randomize hashing by using a salt. The former provides domain separation, helping to avoid collisions between applications/use cases. The latter can also be used for this purpose but is primarily designed for digital signature schemes.

However, unkeyed hashes do not provide authentication (e.g., for Encrypt-then-MAC). Furthermore, they should be avoided for key derivation. Use the linked APIs instead.

BLAKE2b is NOT suitable for hashing passwords. Use Argon2id instead.

A hash size of at least 256 bits is strongly recommended to obtain collision resistance.

Usage

ComputeHash

Fills a span with a hash computed from a message.

BLAKE2b.ComputeHash(Span<byte> hash, ReadOnlySpan<byte> message)

Exceptions

ArgumentOutOfRangeException

hash has a length less than MinHashSize or greater than MaxHashSize.

CryptographicException

Error computing hash.

ComputeHash

Fills a span with a personalized and/or salted hash computed from a message.

BLAKE2b.ComputeHash(Span<byte> hash, ReadOnlySpan<byte> message, ReadOnlySpan<byte> personalization, ReadOnlySpan<byte> salt = default)

Exceptions

ArgumentOutOfRangeException

hash has a length less than MinHashSize or greater than MaxHashSize.

ArgumentOutOfRangeException

personalization and salt both have a length of 0.

ArgumentOutOfRangeException

personalization has a length greater than 0 but not equal to PersonalizationSize.

ArgumentOutOfRangeException

salt has a length greater than 0 but not equal to SaltSize.

CryptographicException

Error computing personalized/salted hash.

IncrementalBLAKE2b

Provides support for computing a hash from several messages.

using var blake2b = new IncrementalBLAKE2b(int hashSize);
blake2b.Update(ReadOnlySpan<byte> message1);
blake2b.Update(ReadOnlySpan<byte> message2);
blake2b.Finalize(Span<byte> hash1);

// Avoid another using statement
blake2b.Reinitialize(int hashSize);
blake2b.Update(ReadOnlySpan<byte> message3);
// Cache the state
blake2b.CacheState();
blake2b.Finalize(Span<byte> hash2);

// Restore the cached state
blake2b.RestoreCachedState();
// hash3 == hash2
blake2b.Finalize(Span<byte> hash3);

// Compute a personalized and/or salted hash
using var blake2b = new IncrementalBLAKE2b(int hashSize, key: ReadOnlySpan<byte>.Empty, ReadOnlySpan<byte> personalization, ReadOnlySpan<byte> salt = default);
blake2b.Update(ReadOnlySpan<byte> message4);
blake2b.Finalize(Span<byte> hash4);

CacheState() can only cache the state once. Each subsequent call will overwrite the previously cached state. See the Notes for when this method should be used.

Do NOT use this class with multiple threads. If you absolutely have to, you need to use lock statements to avoid exceptions being thrown.

Exceptions

ArgumentOutOfRangeException

hashSize is less than MinHashSize or greater than MaxHashSize.

ArgumentOutOfRangeException

personalization has a length greater than 0 but not equal to PersonalizationSize.

ArgumentOutOfRangeException

salt has a length greater than 0 but not equal to SaltSize.

ArgumentOutOfRangeException

hash has a length not equal to hashSize.

OutOfMemoryException

Allocating memory for the state failed.

CryptographicException

Error initializing/updating/finalizing hash function state.

InvalidOperationException

Cannot update after finalizing or finalize twice (without reinitializing or restoring a cached state).

InvalidOperationException

Cannot cache the state after finalizing (without reinitializing).

InvalidOperationException

Cannot restore the state when it has not been cached or when the current hash size differs from what was cached.

InvalidOperationException

Methods cannot be called from multiple threads simultaneously.

ObjectDisposedException

The object has been disposed.

Constants

These are used for validation and/or save you defining your own constants.

public const int HashSize = 32;
public const int MinHashSize = 16;
public const int MaxHashSize = 64;
public const int BlockSize = 128;
public const int SaltSize = 16;
public const int PersonalizationSize = 16;

Notes

Do NOT use ComputeHash() for key derivation. Read the Key derivation page instead.

Do NOT manually truncate a hash. Instead, specify the hash size you want directly. The hash size affects the output, which provides domain separation.

Unlike older hash functions (e.g., MD5, SHA-1, SHA-256, and SHA-512), BLAKE2b is immune to length extension attacks.

If you are making multiple calls to IncrementalBLAKE2b with unchanging/static data at the beginning, you can cache the state to improve performance. This allows you to only process this data once. It is more relevant in message authentication scenarios, as explained on that page.

The security level of BLAKE2b is 1/2 the output length (e.g., 128-bit security for a 256-bit hash).​