KZ.FileHash 1.1.0

KZ.FileHash

KZ.FileHash is a lightweight .NET library for calculating cryptographic hashes of files and streams asynchronously.

It is designed for applications that need reliable and memory-efficient file hashing without loading the entire file into memory.

The library supports multiple hashing algorithms, progress reporting, cancellation, file streams, and non-seekable streams.

🚀 Performance & Benchmarks

We continuously monitor execution speed and memory allocations using BenchmarkDotNet and GitHub Actions.

📊 Click the badge above to view the full interactive performance graphs across commits.

Features

• Calculate hashes asynchronously.
• Calculate multiple hashes in a single read operation.
• Supports files and streams.
• Supports seekable and non-seekable streams.
• Optional progress reporting from 0 to 100.
• Supports CancellationToken.
• Uses buffered asynchronous I/O.
• Uses ArrayPool<byte> to reduce memory allocations.
• Uses IncrementalHash for streaming hash calculation.
• Does not load the entire file into memory.
• Returns hexadecimal hash strings.
• Supports combining multiple algorithms using [Flags].
• Compatible with modern .NET applications.
• Supports .NET 8.0, .NET 9.0, and .NET 10.0 (multi-targeting).
• Customizable buffer size – You can fine-tune the internal buffer for your specific environment.
• Default buffer size 64 KB – optimized to avoid the Large Object Heap (LOH) while delivering great performance.

Supported Algorithms

KZ.FileHash currently supports the following algorithms:

Security note: MD5 and SHA-1 are considered cryptographically weak for security-sensitive applications. They are provided primarily for compatibility and integrity-checking scenarios where collision resistance is not a security requirement.

Installation

Install the package from NuGet:

dotnet add package KZ.FileHash

Requirements & Defaults

Quick Start

using KZ.FileHash.Engine;
using KZ.FileHash.Enums;

var engine = new FileHashEngine(HashAlgorithmType.SHA256);

var hashes = await engine.CalculateHashAsync("example.zip");

Console.WriteLine(hashes[HashAlgorithmType.SHA256]);

Multiple Algorithms

Multiple algorithms can be calculated in a single read operation:

var engine = new FileHashEngine(
    HashAlgorithmType.MD5 |
    HashAlgorithmType.SHA256 |
    HashAlgorithmType.SHA512);

var hashes = await engine.CalculateHashAsync("example.zip");

Console.WriteLine(hashes[HashAlgorithmType.MD5]);
Console.WriteLine(hashes[HashAlgorithmType.SHA256]);
Console.WriteLine(hashes[HashAlgorithmType.SHA512]);

Stream Support

KZ.FileHash also supports hashing directly from streams:

await using var stream = File.OpenRead("example.zip");

var engine = new FileHashEngine(HashAlgorithmType.SHA256);

var hashes = await engine.CalculateHashAsync(stream);

Console.WriteLine(hashes[HashAlgorithmType.SHA256]);

Progress Reporting

Progress reporting is optional:

var progress = new Progress<double>(value =>
{
    Console.WriteLine($"{value:F2}%");
});

var engine = new FileHashEngine(HashAlgorithmType.SHA256);

var hashes = await engine.CalculateHashAsync(
    "large-file.iso",
    progress);

Customize buffer size

var progress = new Progress<double>(value =>
{
    Console.WriteLine($"{value:F2}%");
});

var engine = new FileHashEngine(HashAlgorithmType.SHA256, 1024 * 1024);

var hashes = await engine.CalculateHashAsync(
    "large-file.iso",
    progress);

Cancellation

Hash calculation supports cancellation through CancellationToken:

using var cts = new CancellationTokenSource();

var engine = new FileHashEngine(HashAlgorithmType.SHA256);

var hashes = await engine.CalculateHashAsync(
    "large-file.iso",
    cancellationToken: cts.Token);

AlgorithmsHelper

AlgorithmsHelper provides utilities for working with supported algorithms.

using KZ.FileHash.Enums;
using KZ.FileHash.Helpers;

var length =
    AlgorithmsHelper.GetAlgorithmHexStringLength(
        HashAlgorithmType.SHA256);

var algorithms =
    AlgorithmsHelper.GetAlgorithmsByLength(64);

var name =
    AlgorithmsHelper.GetAlgorithmName(
        HashAlgorithmType.SHA256);

Security Note

MD5 and SHA-1 are cryptographically weak and should not be used for security-sensitive applications.

They are included primarily for compatibility and non-security-critical integrity checking.

For modern applications, SHA-256, SHA-384, SHA-512, or SHA-3 variants are recommended.

License

KZ.FileHash is licensed under the MIT License.

See the LICENSE file for details.

Author

Kareem Zein

• GitHub: https://github.com/Kareem-Zein
• Website: https://kareem-zein.com