Class Blake3

Namespace

CryptoHives.Foundation.Security.Cryptography.Hash

Assembly

CryptoHives.Foundation.Security.Cryptography.dll

Computes the BLAKE3 hash for the input data.

public sealed class Blake3 : HashAlgorithm, ICryptoTransform, IDisposable, IResettable, IExtendableOutput

Inheritance

object

HashAlgorithm

HashAlgorithm

Blake3

Implements

ICryptoTransform

IDisposable

IResettable

IExtendableOutput

Inherited Members

HashAlgorithm.Create(string, bool)

HashAlgorithm.Create(string)

HashAlgorithm.AppendData(ReadOnlySpan<byte>)

HashAlgorithm.AppendData(in ReadOnlySequence<byte>)

HashAlgorithm.TryGetHashAndReset(Span<byte>, out int)

HashAlgorithm.ComputeHash(Stream)

HashAlgorithm.ComputeHash(byte[])

HashAlgorithm.ComputeHash(byte[], int, int)

HashAlgorithm.TransformBlock(byte[], int, int, byte[], int)

HashAlgorithm.TransformFinalBlock(byte[], int, int)

HashAlgorithm.Dispose()

HashAlgorithm.Clear()

HashAlgorithm.HashSize

HashAlgorithm.Hash

HashAlgorithm.InputBlockSize

HashAlgorithm.OutputBlockSize

HashAlgorithm.CanTransformMultipleBlocks

HashAlgorithm.CanReuseTransform

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Remarks

This is a fully managed implementation of BLAKE3 that does not rely on OS or hardware cryptographic APIs, ensuring deterministic behavior across all platforms and runtimes.

BLAKE3 is a cryptographic hash function that is much faster than SHA-256 while maintaining high security. It supports variable output length (XOF mode).

BLAKE3 supports three modes: standard hashing, keyed hashing (MAC), and key derivation.

Constructors

Blake3()

Initializes a new instance of the Blake3 class with default output size (32 bytes).

public Blake3()

Blake3(int)

Initializes a new instance of the Blake3 class with specified output size.

public Blake3(int outputBytes)

Parameters

outputBytes int

The desired output size in bytes.

Fields

BlockSizeBytes

The block size in bytes.

public const int BlockSizeBytes = 64

Field Value

int

ChunkSizeBytes

The chunk size in bytes (1024 bytes).

public const int ChunkSizeBytes = 1024

Field Value

int

DefaultHashSizeBits

The default hash size in bits.

public const int DefaultHashSizeBits = 256

Field Value

int

DefaultHashSizeBytes

The default hash size in bytes.

public const int DefaultHashSizeBytes = 32

Field Value

int

KeySizeBytes

The required key size in bytes for keyed hash mode.

public const int KeySizeBytes = 32

Field Value

int

Properties

AlgorithmName

Gets the name of the hash algorithm.

public override string AlgorithmName { get; }

Property Value

string

BlockSize

Gets the block size in bytes used by the hash algorithm.

public override int BlockSize { get; }

Property Value

int

IsInitialized

Gets a value indicating whether this instance is already in the state Initialize() would produce, so TryReset() can skip resetting it.

protected override bool IsInitialized { get; }

Property Value

bool

true if a reset would be a no-op; otherwise, false.

Mode

Gets the mode of operation for this instance.

public Blake3Mode Mode { get; }

Property Value

Blake3Mode

Methods

Absorb(ReadOnlySpan<byte>)

Absorbs input data into the XOF state.

public void Absorb(ReadOnlySpan<byte> input)

Parameters

input ReadOnlySpan<byte>

The input data to absorb.

Exceptions

InvalidOperationException

Thrown when data is added after output has been squeezed.

Create()

Creates a new instance of the Blake3 class with default output size.

public static Blake3 Create()

Returns

Blake3

A new BLAKE3 instance.

Create(int)

Creates a new instance of the Blake3 class with specified output size.

public static Blake3 Create(int outputBytes)

Parameters

outputBytes int

The desired output size in bytes.

Returns

Blake3

A new BLAKE3 instance.

CreateDeriveKey(ReadOnlySpan<byte>)

Creates a new instance of the Blake3 class in derive-key mode from a pre-encoded context string.

public static Blake3 CreateDeriveKey(ReadOnlySpan<byte> contextUtf8)

Parameters

contextUtf8 ReadOnlySpan<byte>

The UTF-8 encoded context string. Must not be empty. See CreateDeriveKey(string).

Returns

Blake3

A new BLAKE3 instance configured for key derivation.

Remarks

Use this overload when the context is already available as UTF-8 bytes -- a u8 literal, for instance -- to skip the string encoding entirely.

CreateDeriveKey(ReadOnlySpan<byte>, int)

Creates a new instance of the Blake3 class in derive-key mode from a pre-encoded context string, with a specified output size.

public static Blake3 CreateDeriveKey(ReadOnlySpan<byte> contextUtf8, int outputBytes)

Parameters

contextUtf8 ReadOnlySpan<byte>

The UTF-8 encoded context string. Must not be empty. See CreateDeriveKey(string).

outputBytes int

The desired output size in bytes.

Returns

Blake3

A new BLAKE3 instance configured for key derivation.

CreateDeriveKey(string)

Creates a new instance of the Blake3 class in derive-key mode.

public static Blake3 CreateDeriveKey(string context)

Parameters

context string

The context string. Must not be empty.

Returns

Blake3

A new BLAKE3 instance configured for key derivation.

Remarks

The context string is domain separation, not a secret and not an input: the BLAKE3 spec requires it to be a hard-coded, application-specific, globally unique constant. It must never be user input, attacker-controlled, or varied per call -- put the varying material in the key material hashed by the returned instance instead. A good context embeds the application name, a date and the purpose, e.g. "MyApp 2026-01-01 session key".

The returned instance derives from the key material written to it, so callers hash the input key material and read out the derived key -- optionally longer than 32 bytes, since derive-key mode is a full XOF.

CreateDeriveKey(string, int)

Creates a new instance of the Blake3 class in derive-key mode with a specified output size.

public static Blake3 CreateDeriveKey(string context, int outputBytes)

Parameters

context string

The context string. Must not be empty. See CreateDeriveKey(string).

outputBytes int

The desired output size in bytes.

Returns

Blake3

A new BLAKE3 instance configured for key derivation.

Exceptions

ArgumentNullException

context is null.

CreateKeyed(ReadOnlySpan<byte>)

Creates a new keyed instance of the Blake3 class.

public static Blake3 CreateKeyed(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The 32-byte key for keyed hashing.

Returns

Blake3

A new BLAKE3 instance configured for keyed hashing.

CreateKeyed(ReadOnlySpan<byte>, int)

Creates a new keyed instance of the Blake3 class with specified output size.

public static Blake3 CreateKeyed(ReadOnlySpan<byte> key, int outputBytes)

Parameters

key ReadOnlySpan<byte>

The 32-byte key for keyed hashing.

outputBytes int

The desired output size in bytes.

Returns

Blake3

A new BLAKE3 instance configured for keyed hashing.

Dispose(bool)

Releases the unmanaged resources used by the HashAlgorithm and optionally releases the managed resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

HashCore(ReadOnlySpan<byte>)

When overridden in a derived class, routes data written to the object into the hash algorithm for computing the hash.

protected override void HashCore(ReadOnlySpan<byte> source)

Parameters

source ReadOnlySpan<byte>

The input to compute the hash code for.

Exceptions

ObjectDisposedException

Thrown when the instance has been disposed.

HashData(in ReadOnlySequence<byte>)

Computes the BLAKE3 hash of source using the default output size (32 bytes) and returns it as a new byte array.

public static byte[] HashData(in ReadOnlySequence<byte> source)

Parameters

source ReadOnlySequence<byte>

The (possibly multi-segment) input sequence to hash.

Returns

byte[]

A new byte array containing the BLAKE3 hash.

HashData(ReadOnlySpan<byte>)

Computes the BLAKE3 hash of source using the default output size (32 bytes) and returns it as a new byte array.

public static byte[] HashData(ReadOnlySpan<byte> source)

Parameters

source ReadOnlySpan<byte>

The input data to hash.

Returns

byte[]

A new byte array containing the BLAKE3 hash.

Remarks

Rents a pooled instance and takes the dedicated one-shot path — the same path TryComputeHash(ReadOnlySpan<byte>, Span<byte>, out int) takes on a freshly initialized instance — so the entire call, small inputs included, skips the incremental chunk-buffer bookkeeping the streaming surface needs.

Initialize()

Initializes an implementation of the HashAlgorithm class.

public override void Initialize()

Exceptions

ObjectDisposedException

Thrown when the instance has been disposed.

Reset()

Resets the XOF state so the instance can be reused for a new computation.

public void Reset()

Remarks

After calling this method, the instance is in the same state as a newly constructed one. All previously absorbed data and squeezed output are discarded.

Squeeze(Span<byte>)

Finalizes the hash and squeezes output of the specified length.

public void Squeeze(Span<byte> output)

Parameters

output Span<byte>

The buffer to receive the output.

Exceptions

ObjectDisposedException

Thrown when the instance has been disposed.

TryComputeHash(ReadOnlySpan<byte>, Span<byte>, out int)

Attempts to compute the hash value for the specified read-only byte span and writes the result into the provided destination span.

public override bool TryComputeHash(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten)

Parameters

source ReadOnlySpan<byte>

The input to compute the hash code for.

destination Span<byte>

The buffer to receive the hash value.

bytesWritten int

When this method returns, the total number of bytes written into destination.

Returns

bool

true if destination is long enough to receive the hash value; otherwise, false.

Remarks

The algorithm is automatically reset after a successful computation, allowing the instance to be reused for subsequent AppendData(ReadOnlySpan<byte>) calls or another TryComputeHash(ReadOnlySpan<byte>, Span<byte>, out int) without calling Initialize() first.

The base implementation feeds source through the streaming HashCore/TryHashFinal pair. An algorithm with a dedicated single-call path that is faster than streaming — BLAKE3's tree hashing, for instance — should override this and dispatch to it. An override must preserve the auto-reset above and must still honour data already appended to this instance, falling back to base.TryComputeHash when its one-shot path needs a freshly initialized state.

Exceptions

ObjectDisposedException

Thrown when the instance has been disposed.

TryHashData(in ReadOnlySequence<byte>, Span<byte>, out int)

Computes the BLAKE3 hash of source using the default output size (32 bytes) and writes it into destination.

public static bool TryHashData(in ReadOnlySequence<byte> source, Span<byte> destination, out int bytesWritten)

Parameters

source ReadOnlySequence<byte>

The (possibly multi-segment) input sequence to hash.

destination Span<byte>

The buffer to receive the hash value. Must be at least DefaultHashSizeBytes bytes.

bytesWritten int

When this method returns, the number of bytes written into destination.

Returns

bool

true if destination was large enough; otherwise, false.

TryHashData(ReadOnlySpan<byte>, Span<byte>, out int)

Computes the BLAKE3 hash of source using the default output size (32 bytes) and writes it into destination.

public static bool TryHashData(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten)

Parameters

source ReadOnlySpan<byte>

The input data to hash.

destination Span<byte>

The buffer to receive the hash value. Must be at least DefaultHashSizeBytes bytes.

bytesWritten int

When this method returns, the number of bytes written into destination.

Returns

bool

true if destination was large enough; otherwise, false.

Remarks

Rents a pooled instance and takes the dedicated one-shot path — the same path TryComputeHash(ReadOnlySpan<byte>, Span<byte>, out int) takes on a freshly initialized instance — so the entire call, small inputs included, skips the incremental chunk-buffer bookkeeping the streaming surface needs.

TryHashFinal(Span<byte>, out int)

When overridden in a derived class, finalizes the hash computation and writes the result into the provided buffer.

protected override bool TryHashFinal(Span<byte> destination, out int bytesWritten)

Parameters

destination Span<byte>

The target buffer to write the hash to.

bytesWritten int

The number of bytes written into the buffer.

Returns

bool

true if the destination buffer was large enough; otherwise false.

Exceptions

ObjectDisposedException

Thrown when the instance has been disposed.

TryReset()

Resets this instance to its initial state so it can be returned to an object pool for reuse.

public override bool TryReset()

Returns

bool

true if the instance was reset and may be returned to the pool; false if it must instead be disposed and discarded (see remarks).

Remarks

This method implements IResettable from Microsoft.Extensions.ObjectPool, enabling any CryptoHives hash algorithm to be used with DefaultObjectPool<T> without a custom policy.

Overridden by algorithms that can carry caller-supplied secret material (e.g. a keyed BLAKE3 instance): those return false so the pool's policy disposes the instance — erasing the secret — instead of recycling it for an unrelated caller.

The reset is skipped when IsInitialized already reports the initial state. That is the common case for a pooled instance: every helper in HashAlgorithmPool<T> finishes with TryComputeHash(ReadOnlySpan<byte>, Span<byte>, out int) or TryGetHashAndReset(Span<byte>, out int), both of which end in Initialize() on success, so the instance handed back to the pool is already reset and doing it again is pure cost.