Zhomfr.Hash.Abstractions 0.7.0

Abstractions for Unified Work with Hashes.

⚠️ Warning: Active Development (< 1.0.0)

Prior to the release of stable version 1.0.0, this library follows SemVer for initial development. This means breaking changes may occur even in minor releases (0.x).

We strongly recommend pinning the package version in your .csproj to avoid unexpected build errors.

A lightweight and flexible .NET library providing a unified contract for hash functions. It completely decouples your business logic from specific hashing algorithms or third-party implementations.

💡 Core Concept

Your code interacts exclusively with a standardized interface. The underlying algorithm is determined at the dependency injection composition root. If you ever need to change the algorithm or provider tomorrow, you won't need to rewrite your business logic.

Available Drivers:

• Argon2 see GitHub NuGet

Development Custom Driver

📦 Installation

Install package:

dotnet add package Zhomfr.Hash.Abstractions

For example, you can use code of available drivers in GitHub.

Configuration Convention

All settings are located in appsettings.json under the Zhomfr:Hash section:

• The default service uses the Zhomfr:Hash:Default subsection.
• Keyed services use subsections where the name matches the service key, resulting in Zhomfr:Hash:KeyName.

For instance, given the following registrations:

builder.Services.AddDefaultHash<MyAwesomeHash, MyAwesomeHashConfig>();
builder.Services.AddKeyedHash<MyAwesomeHash, MyAwesomeHashConfig>("AwesomeKey");

Your appsettings.json file should follow this structure:

{
  "Zhomfr": {
    "Hash": {
      "Default": {
        "Secret": "someSecretForDefault"
        // ... other configuration properties
      },
      "AwesomeKey": {
        "Secret": "someSecretForAwesomeKey"
        // ... other configuration properties
      }
    }
  }
}

IHash

Namespace: Zhomfr.Hash.Abstractions

Defines methods for secure password hashing and verification.

public interface IHash

Attributes NullableContextAttribute

Methods

Make (String)

Creates a secure hash for the specified password.

string Make(string password)

Parameters

password String<br> The plain-text password to be hashed.

Returns

String<br> A string containing the hash along with metadata (version, salt, and algorithm parameters) for subsequent storage in a database.

Check (String, String)

Verifies that the provided password matches the stored hash.

bool Check(string password, string storedHash)

Parameters

password String<br> The plain-text password to verify.

storedHash String<br> The full hash string previously generated via the IHash.Make (String) method.

Returns

Boolean<br> True if the password is correct; otherwise, false.

Remarks:

The implementation should use fixed-time comparison to prevent side-channel timing attacks.

NeedsRehash (String)

Determines if the password hash needs to be updated due to changes in security settings.

bool NeedsRehash(string storedHash)

Parameters

storedHash String<br> The current hash from the data store.

Returns

Boolean<br> True if the system's algorithm parameters (e.g., MemorySize or Iterations) differ from those embedded in the hash.

Remarks:

If this method returns true, it is recommended to re-create the hash using IHash.Make (String) during the user's next successful authentication.