IncrementalHash Struct

Represents the state of a hash algorithm that can be incrementally updated with segments of data.

public readonly struct IncrementalHash

The type provides an “init, update, final” interface for hashing data: First, a state needs to be initialized with the hash algorithm to be used. The state can then be updated zero or more times with segments of data. Finalizing the state yields a result that is identical to the hash of the concatenated segments.

IncrementalHash instances have value-type semantics: Passing an instance to a method or assigning it to a variable creates a copy of the state.

Example

The following C# example shows how to compute a hash from multiple segments of data:

// select the BLAKE2b-256 algorithm
var algorithm = HashAlgorithm.Blake2b_256;

// initialize the state with the algorithm
IncrementalHash.Initialize(algorithm, out var state);

// incrementally update the state with some data
var lines = new[]
{
    "It is a period of civil war.\n",
    "Rebel spaceships, striking\n",
    "from a hidden base, have won\n",
    "their first victory against\n",
    "the evil Galactic Empire.\n"
};
foreach (var line in lines)
{
    IncrementalHash.Update(ref state, Encoding.UTF8.GetBytes(line));
}

// finalize the computation and get the result
var hash = IncrementalHash.Finalize(ref state);

Summary

Properties

Algorithm

Gets the algorithm that was used to initialize the state.

public HashAlgorithm? Algorithm { get; }

Property Value

An instance of the HashAlgorithm class, or null if the current instance has not been initialized yet or if it has been finalized.

Static Methods

Initialize(HashAlgorithm, out IncrementalHash)

Initializes the IncrementalHash state with the specified hash algorithm.

public static void Initialize(
    HashAlgorithm algorithm,
    out IncrementalHash state)

Parameters

algorithm
The hash algorithm to use for computing the hash.
state
When this method returns, contains the initialized state.

Exceptions

ArgumentNullException
algorithm is null.

Update(ref IncrementalHash, ReadOnlySpan<byte>)

Updates the IncrementalHash state with the specified span of bytes.

public static void Update(
    ref IncrementalHash state,
    ReadOnlySpan<byte> data)

Parameters

state
The state to be updated with data.
data
A segment of the data to hash.

Exceptions

InvalidOperationException
state has not been initialized yet or has already been finalized.

Finalize(ref IncrementalHash)

Completes the hash computation and returns the result as an array of bytes.

public static byte[] Finalize(
    ref IncrementalHash state)

Parameters

state
The state to be finalized.

Return Value

The computed hash.

Exceptions

InvalidOperationException
state has not been initialized yet or has already been finalized.

Finalize(ref IncrementalHash, Span<byte>)

Completes the hash computation and fills the specified span of bytes with the result.

public static void Finalize(
    ref IncrementalHash state,
    Span<byte> hash)

Parameters

state
The state to be finalized.
hash
The span to fill with the computed hash.

Exceptions

InvalidOperationException
state has not been initialized yet or has already been finalized.
ArgumentException
hash.Length is not equal to HashSize.

FinalizeAndVerify(ref IncrementalHash, ReadOnlySpan<byte>)

Completes the hash computation and verifies that the result equals the specified hash.

public static bool FinalizeAndVerify(
    ref IncrementalHash state,
    ReadOnlySpan<byte> hash)

Parameters

state
The state to be finalized.
hash
The hash to be verified.

Return Value

true if verification succeeds; otherwise, false.

Exceptions

InvalidOperationException
state has not been initialized yet or has already been finalized.

Thread Safety

Any public static members of this type are thread safe. Any instance members are not guaranteed to be thread safe. As with any other type, reading and writing to a shared variable that contains an instance of this type must be protected by a lock to guarantee thread safety.

See Also