Key derivation

Purpose

BLAKE2b can be used as a key derivation function (KDF) for high-entropy keys. It takes the following parameters to produce 256 to 512 bits of output keying material:

• 256 to 512 bits of input keying material (e.g., a shared secret).

• A 128-bit personalization constant (e.g., an application/protocol name).

• A 128-bit salt (e.g., a counter or random data).

• Optional contextual info of any length (e.g., an explanation of what the key will be used for).

This allows you to derive new, distinct keys from a high-entropy master key. For example, separate keys for encryption and authentication with Encrypt-then-MAC by changing the personalization constant, salt, and/or info.

BLAKE2b is NOT suitable for deriving keys from passwords. Use Argon2id instead.

256-bit keys are recommended. Larger keys are unnecessary unless splitting the output in two (e.g., keys for different directions) or doing a symmetric ratchet (the state size should be double the security level).

Usage

DeriveKey

Fills a span with output keying material computed from input keying material, a personalization constant, a salt, and optional additional contextual info.

BLAKE2b.DeriveKey(Span<byte> outputKeyingMaterial, ReadOnlySpan<byte> inputKeyingMaterial, ReadOnlySpan<byte> personalization, ReadOnlySpan<byte> salt = default, ReadOnlySpan<byte> info = default)

Exceptions

ArgumentOutOfRangeException

outputKeyingMaterial has a length less than MinKeySize or greater than MaxKeySize.

ArgumentOutOfRangeException

inputKeyingMaterial has a length less than MinKeySize or greater than MaxKeySize.

ArgumentOutOfRangeException

personalization has a length not equal to PersonalizationSize.

ArgumentOutOfRangeException

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

CryptographicException

The key could not be derived.

IncrementalBLAKE2b

Provides support for computing output keying material from several messages.

using var blake2b = new IncrementalBLAKE2b(int hashSize, ReadOnlySpan<byte> inputKeyingMaterial, ReadOnlySpan<byte> personalization, ReadOnlySpan<byte> salt = default);
blake2b.Update(ReadOnlySpan<byte> info1);
blake2b.Update(ReadOnlySpan<byte> info2);
blake2b.Finalize(Span<byte> outputKeyingMaterial1);

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

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

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

key has a length less than MinKeySize or greater than MaxKeySize.

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.

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 KeySize = 32;
public const int SaltSize = 16;
public const int PersonalizationSize = 16;
public const int MinKeySize = 32;
public const int MaxKeySize = 64;
public const int BlockSize = 128;

Notes

The input keying material MUST be high in entropy (e.g., a shared secret).

Do NOT use the same output keying material for multiple purposes (e.g., encryption and authentication). You should derive separate keys using the same input keying material and personalization but different salts and/or info.

If you intend to feed multiple variable-length inputs into the info, beware of canonicalization attacks. Please read the Concat page for more information.

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.