Message authentication
Purpose
BLAKE2b is a cryptographic hash function and message authentication code (MAC). As a MAC, it takes a message of any size and a 256-bit to 512-bit key and produces a 128-bit to 512-bit tag.
This tag allows you to verify that a message has not been tampered with. A change to the message or the use of a different key will result in a different tag, at which point you should throw an error.
A tag size of at least 256 bits is strongly recommended to obtain committing security, which requires collision resistance.
A 256-bit key is recommended regardless of the tag size. Larger keys are unnecessary.
Usage
ComputeTag
Fills a span with a tag computed from a message and a key.
BLAKE2b.ComputeTag(Span<byte> tag, ReadOnlySpan<byte> message, ReadOnlySpan<byte> key)Exceptions
tag has a length less than MinTagSize or greater than MaxTagSize.
key has a length less than MinKeySize or greater than MaxKeySize.
The tag could not be computed.
VerifyTag
Verifies that a tag is correct in constant time for a given message and key. It returns true if the tag is valid and false otherwise.
BLAKE2b.VerifyTag(ReadOnlySpan<byte> tag, ReadOnlySpan<byte> message, ReadOnlySpan<byte> key)Exceptions
tag has a length less than MinTagSize or greater than MaxTagSize.
key has a length less than MinKeySize or greater than MaxKeySize.
The tag could not be recomputed.
IncrementalBLAKE2b
Provides support for computing a tag from several messages and a key.
using var blake2b = new IncrementalBLAKE2b(int hashSize, ReadOnlySpan<byte> key);
blake2b.Update(ReadOnlySpan<byte> message1);
blake2b.Update(ReadOnlySpan<byte> message2);
// Compute
blake2b.Finalize(Span<byte> tag1);
// Or verify
bool valid = blake2b.FinalizeAndVerify(ReadOnlySpan<byte> tag1);
// Avoid another using statement
blake2b.Reinitialize(int hashSize, ReadOnlySpan<byte> key);
// Cache the state
blake2b.CacheState();
blake2b.Update(ReadOnlySpan<byte> message3);
blake2b.Finalize(Span<byte> tag2);
// Restore the cached state
blake2b.RestoreCachedState();
blake2b.Update(ReadOnlySpan<byte> message3);
// tag3 == tag2
blake2b.Finalize(Span<byte> tag3);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.
Exceptions
hashSize is less than MinHashSize or greater than MaxHashSize.
key has a length less than MinKeySize or greater than MaxKeySize.
hash has a length not equal to hashSize.
The tag could not be computed.
Cannot update after finalizing or finalize twice (without reinitializing or restoring a cached state).
Cannot cache the state after finalizing (without reinitializing).
Cannot restore the state when it has not been cached.
The object has been disposed.
Constants
These are used for validation and/or save you defining your own constants.
public const int TagSize = 32;
public const int KeySize = 32;
public const int MinTagSize = 16;
public const int MaxTagSize = 64;
public const int MinKeySize = 16;
public const int MaxKeySize = 64;Notes
Tags MUST be compared in constant time to avoid leaking information, so use the VerifyTag() or FinalizeAndVerify() function.
With Encrypt-then-MAC, you MUST include the nonce in the message when computing the tag.
If you intend to feed multiple variable-length inputs into the message, beware of canonicalization attacks. Please read the Concat page for more information.
The key MUST be uniformly random. It should be the output of a KDF, NOT randomly generated.
Do NOT use the same key for multiple purposes (e.g. encryption and authentication). You should derive separate keys using the same input keying material and personalisation but different salts and/or info.
The same key can be reused for multiple messages, but it is good practice to derive a unique key each time.
If you are making multiple calls to IncrementalBLAKE2b with unchanging/static data at the beginning (e.g. the same key), you can cache the state to improve performance. This allows you to only process this data once and can help you quickly zero the key from memory.
Last updated