IResumableHashAlgorithm Interface

Definition

Namespace

Bodu.IO.Hashing

Assembly

Bodu.IO.Hashing.dll

Package

Bodu.IO.Hashing 1.0.0

Source

IResumableHashAlgorithm.cs

Marks a non-cryptographic hash algorithm whose internal state can be reconstructed from a previously emitted digest, so additional input can be folded into an existing hash without re-reading the bytes that produced it.

public interface IResumableHashAlgorithm

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

Many simple, additive non-cryptographic hashes - CRC, FNV, Jenkins-style mixes - are linear in the sense that the running accumulator at any point is fully determined by the bytes seen so far. The published digest hides that accumulator behind a finalization step (typically a final XOR, output reflection, or width mask), but the step is reversible. Implementing IResumableHashAlgorithm declares that an algorithm supports that reverse step and exposes a stable contract for callers who want to incrementally hash a stream that arrives in chunks across process boundaries - a common pattern in tail-anchored log files, content-addressed stores, or streaming integrity checks where the running state is not in memory but the previous digest is.

Usage shape. Pair the previous digest with the new bytes:

• ComputeHashFrom(ReadOnlySpan<byte>, ReadOnlySpan<byte>) Returns a freshly allocated digest representing hash(previousInput || newData). The two array overloads are conveniences for callers without spans.
• TryComputeHashFrom(ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>, out int) The allocation-free variant that writes into a caller-supplied buffer; returns false when the destination is too small, leaving bytesWritten at 0.

Implementation contract. Implementations must (a) accept any byte sequence of length HashLengthInBytes as a valid previousHash; (b) reverse any final XOR, reflection, or width mask before resuming; (c) re-apply finalization before returning the new digest; and (d) leave the algorithm instance in a clean state on return. The contract is not preserved across algorithms - a digest produced by CRC-32/ISO-HDLC can only be resumed by an instance configured with the same CrcStandard.

When this is the wrong tool. Cryptographic hashes (SHA-2, SHA-3, BLAKE) are not resumable in this sense - their finalization collapses internal state irreversibly, which is precisely the property that makes them cryptographically useful. For appending to an in-memory algorithm instance, prefer the standard Append(ReadOnlySpan<byte>) path. IResumableHashAlgorithm only earns its keep when the running accumulator has already been discarded and only the digest remains.

using Bodu.IO.Hashing;
using Bodu.IO.Hashing.Checksums;

// 1. Compute a baseline digest of a file's first segment.
var crc = new Crc(CrcStandard.CRC32_ISOHDLC);
crc.Append(File.ReadAllBytes("part-1.bin"));
byte[] digest1 = crc.GetCurrentHash();

// 2. Hours (or processes) later, fold an additional segment into the same
// digest using only `digest1`.
var resumable = (IResumableHashAlgorithm)new Crc(CrcStandard.CRC32_ISOHDLC);
byte[] digest2 = resumable.ComputeHashFrom(digest1, File.ReadAllBytes("part-2.bin"));

// 3. Same result as if both segments had been appended in one session - without
// holding the running state.

Properties

HashLengthInBytes

Gets the length, in bytes, of the digests this algorithm produces and accepts as previousHash.

int HashLengthInBytes { get; }

Property Value

int

The digest length in bytes.

Remarks

Implementers deriving from NonCryptographicHashAlgorithm satisfy this member implicitly through the base class's property of the same name.

Methods

ComputeHashFrom(byte[], byte[])

Resumes a hash computation from a previously finalized hash value and processes additional input, returning the new finalized hash result as a byte array.

byte[] ComputeHashFrom(byte[] previousHash, byte[] newData)

Parameters

previousHash byte[]

The previously finalized hash value to resume from. Must not be null.

newData byte[]

The additional input data to include in the resumed hash calculation. Must not be null.

Returns

byte[]

A byte array containing the new finalized hash result.

Exceptions

ArgumentNullException

previousHash or newData is null.

ArgumentException

Thrown if the previousHash length does not match HashLengthInBytes.

ComputeHashFrom(byte[], byte[], int, int)

Resumes a hash computation from a previously finalized hash value and processes a specified range of new data, returning the new finalized hash result as a byte array.

byte[] ComputeHashFrom(byte[] previousHash, byte[] newData, int offset, int length)

Parameters

previousHash byte[]

The previously finalized hash value to resume from. Must not be null.

newData byte[]

The buffer containing additional input data. Must not be null.

offset int

The zero-based offset into newData at which to begin reading data.

length int

The number of bytes to read from newData.

Returns

byte[]

A byte array containing the new finalized hash result.

Exceptions

ArgumentNullException

previousHash or newData is null.

ArgumentException

Thrown if the previousHash length does not match HashLengthInBytes, or if the offset and length exceed the bounds of newData.

ComputeHashFrom(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Resumes a hash computation from a previously finalized hash value and processes additional input, returning the new finalized hash result as a byte array.

byte[] ComputeHashFrom(ReadOnlySpan<byte> previousHash, ReadOnlySpan<byte> newData)

Parameters

previousHash ReadOnlySpan<byte>

The previously finalized hash value to resume from.

newData ReadOnlySpan<byte>

The additional input data to include in the resumed hash calculation.

Returns

byte[]

A byte array containing the new finalized hash result.

Exceptions

ArgumentException

Thrown if the previousHash length does not match HashLengthInBytes.

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

Resumes a hash computation from a previously finalized hash value, processes additional input, and writes the new finalized hash to the specified destination span.

bool TryComputeHashFrom(ReadOnlySpan<byte> previousHash, ReadOnlySpan<byte> newData, Span<byte> destination, out int bytesWritten)

Parameters

previousHash ReadOnlySpan<byte>

The previously finalized hash value to resume from.

newData ReadOnlySpan<byte>

The additional input data to include in the resumed hash calculation.

destination Span<byte>

The destination buffer to write the finalized hash value to.

bytesWritten int

Outputs the number of bytes written to the destination buffer.

Returns

bool

true if the resumed and finalized hash was written successfully; otherwise, false if the destination span was too small.

Exceptions

ArgumentException

Thrown if the previousHash length does not match HashLengthInBytes.

Applies to

Product	Versions
.NET	8, 10

See Also

NonCryptographicHashAlgorithm

Crc