Lyo.Hashing 1.0.6

Lyo.Hashing

Digests (SHA-256/384/512), optional MD5 for non-security fingerprints only, non-cryptographic checksums (CRC-32/CRC-32C/CRC-64/Adler-32), hexadecimal encoding (HexEncoding), incremental hashing (HashingStream), sparse file fingerprints (SparseFileFingerprinter), and injectable IHashingService / HashingService. A process-wide default is HashingService.Shared, analogous to Random.Shared.

The public contracts are IHashingService, Hasher, HexEncoding, HashingStream, and SparseFileFingerprinter. HashingService is the default IHashingService implementation. With XML doc generation enabled in the repo, IntelliSense shows the same summaries as this README. Implementation types use <inheritdoc /> where they mirror the interfaces.

Hex letter casing for service helpers uses TextLetterCase (Upper / Lower) from Lyo.Common.

Features

• SHA-2. One-shot buffer hashing on modern .NET. Stream hashing via HashAlgorithm.
• MD5. Legacy compatibility and fingerprints only. Not for security.
• Checksums. Checksummer / ChecksumStream: CRC-32, CRC-32C, CRC-64/ECMA-182, Adler-32 for corruption detection. Not for security.
• IHashingService. Buffers, streams, files, hex encode/parse, timing-safe equality, HMAC-SHA-256/512, fingerprinting, CreateHashingStream, checksums (Checksum / ChecksumValue / ChecksumFileAsync / CreateChecksumStream).
• Hasher. Static digest helpers without allocating a service.
• HexEncoding. Encode/decode hex with explicit casing.
• byte[].ToHexString(). Extension in namespace Lyo.Hashing (ByteArrayHexExtensions). Lowercase hex for historical consistency.
• HashingStream. Wrap any Stream. Hash updates on read/write. GetHash() / GetHashHex.
• Sparse fingerprints. SparseFileFingerprinter samples large files. MD5 of size + samples, and mtime for very large files.
• DI. AddLyoHashing registers HashingService.Shared or a configured HashingService.

Examples

Register with DI

using Lyo.Common.Enums;
using Lyo.Hashing;
using Lyo.Hashing.Registration;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

// Default process-wide singleton (HashingService.Shared)
services.AddLyoHashing();

// Or custom defaults:
services.AddLyoHashing(o =>
{
    o.DefaultHexLetterCase = TextLetterCase.Lower;
    o.FingerprintDefaults.SampleSize = 256;
});

// Or explicit options instance:
// services.AddLyoHashing(myOptions);

using var sp = services.BuildServiceProvider();
var hashing = sp.GetRequiredService<IHashingService>();

Buffers and streams (service)

var digest = hashing.Hash(ContentDigestAlgorithm.Sha256, payload);
var hex = hashing.ToHex(digest); // uses DefaultHexLetterCase from options

using var ms = new MemoryStream(payload);
var digest2 = hashing.Hash(ContentDigestAlgorithm.Sha256, ms);

var fileDigest = await hashing.HashFileAsync(ContentDigestAlgorithm.Sha512, "/path/to/file.bin", ct);

Static Hasher (no service)

var sha256 = Hasher.ComputeSha256(data);
var sha384 = Hasher.ComputeSha384(span);
var fromStream = Hasher.ComputeSha512(stream);

// Generic SHA-2 selector: digestBits 256, 384, or 512
var any = Hasher.ComputeSha2(256, data);

Hex encode / parse / compare

var upper = HexEncoding.ToHexString(digest, TextLetterCase.Upper);
var lower = HexEncoding.ToHexString(digest, TextLetterCase.Lower);
var roundTrip = HexEncoding.FromHex(upper);

// Timing-safe compare (length mismatch → false)
var ok = hashing.FixedTimeEquals(left, right);

// Parse expected hex then compare (invalid hex → false)
var matches = hashing.EqualsHex(digest, expectedHexChars);

byte[] extension (lowercase hex)

using Lyo.Hashing;

byte[] buf = [0xDE, 0xAD];
var s = buf.ToHexString(); // "dead" — always lowercase

HashingStream

using System.Security.Cryptography;
using var inner = File.OpenRead(path);
using var hashingStream = new HashingStream(inner, SHA256.Create());
var buffer = new byte[8192];
int n;
while ((n = await hashingStream.ReadAsync(buffer, ct)) > 0) { /* process buffer */ }
var digest = hashingStream.GetHash();

Checksums (non-cryptographic)

// Numeric value (32-bit checksums in the low bits)
uint crc = Checksummer.ComputeCrc32(payload); // e.g. 0xCBF43926 for "123456789"
ulong crc64 = Checksummer.ComputeValue(ChecksumAlgorithm.Crc64, payload);

// Big-endian bytes (4 for 32-bit, 8 for CRC-64) — flows through HexEncoding/ToHex
byte[] bytes = Checksummer.Compute(ChecksumAlgorithm.Crc32C, payload);

// Service surface (honors HashingOptions.DefaultHexLetterCase via ToHex)
var svc = HashingService.Shared;
byte[] viaSvc = svc.Checksum(ChecksumAlgorithm.Crc32, payload);
byte[] fileCrc = await svc.ChecksumFileAsync(ChecksumAlgorithm.Crc64, "/path/to/file.bin", ct);

// Incremental over a stream
using var cs = svc.CreateChecksumStream(File.OpenRead(path), ChecksumAlgorithm.Crc32);
var buffer = new byte[8192];
while (cs.Read(buffer, 0, buffer.Length) > 0) { /* ... */ }
ulong value = cs.GetChecksumValue();

Sparse file fingerprint

byte[]? fp = await hashing.FingerprintSampledFileAsync(path, new FileInfo(path).Length, ct: ct);
// null if path does not exist

// Metadata-only (size + last write UTC); no content read
var metaHex = SparseFileFingerprinter.MetadataOnlyHex(fileSize, lastWriteTimeUtc);

HMAC

var mac = hashing.HmacSha256(key, payload);
var mac512 = hashing.HmacSha512(key, payload);

Benchmarks

• Portfolio suite: hashing

Choosing an API

Dependency injection

Use using Lyo.Hashing.Registration so extension methods AddLyoHashing resolve on IServiceCollection.

HashingStream

Wrap an inner stream. Every byte read or written updates the hash. Call GetHash() when finished, or GetHashHex for a string. GetHashString() stays uppercase for backward compatibility. Prefer GetHashHex(TextLetterCase) for explicit casing. When created via IHashingService.CreateHashingStream, the correct HashAlgorithm instance is chosen for ContentDigestAlgorithm.

Checksums (non-cryptographic)

For accidental-corruption detection (transport, storage, archive formats). Not for security, signatures, or tamper detection. On modern .NET the CRC-32 and CRC-64 buffer paths delegate to System.IO.Hashing. CRC-32C and Adler-32 use internal implementations that produce identical results across targets.

Sparse file fingerprint

For directory snapshots or "probably unchanged" checks without hashing entire files. Thresholds and sample sizes come from FileFingerprintOptions (service defaults in HashingOptions.FingerprintDefaults).

HMAC

Key lifecycle and storage are caller responsibilities.

HashingOptions

FileFingerprintOptions

ContentDigestAlgorithm

ChecksumAlgorithm

Checksummer.Compute and IHashingService.Checksum return big-endian bytes (4 for 32-bit checksums, 8 for CRC-64); ComputeValue / ChecksumValue return the raw numeric value.

Notes

• MD5 and sparse fingerprints are for compatibility, change detection, or tooling. Do not use them for passwords, signatures, or integrity where an attacker can influence inputs.
• Checksums (CRC / Adler-32) detect accidental corruption only. They are trivially forgeable and must not be used as a security or tamper-detection boundary.
• HashFileAsync throws if the file is missing. FingerprintSampledFileAsync returns null when the path does not exist.
• On netstandard2.0, file hashing uses synchronous HashAlgorithm paths under the hood where async OS APIs are unavailable.

Dependencies

Generated from ProjectReference / PackageReference (same model as docs/Lyo.ProjectGraph.html).

• Lyo.Common (direct, lyo)
• Lyo.Exceptions (direct, lyo)
• Microsoft.Extensions.DependencyInjection.Abstractions 10.0.5 (direct, microsoft)
• System.IO.Hashing 10.0.5 (direct, microsoft, net10.0)
• System.Memory 4.6.3 (direct, microsoft, netstandard2.0)
• Microsoft.Extensions.Logging.Abstractions 10.0.5 (transitive, microsoft)
• System.Text.Json 10.0.5 (transitive, microsoft, netstandard2.0)