Argon2Sharp 3.5.0

<div align="center">

🔐 Argon2Sharp

Pure C# Implementation of Argon2 Password Hashing Algorithm

A modern, high-performance, pure C# implementation of the Argon2 password hashing algorithm following RFC 9106 specification.

Features • Installation • Quick Start • API Reference • Benchmarks

</div>

✨ Features

• Pure C# - No native dependencies, runs anywhere .NET runs
• RFC 9106 compliant - Argon2d, Argon2i, Argon2id support
• Immutable parameters - Thread-safe Argon2Parameters sealed record
• Builder pattern - Fluent API for parameter construction
• Span-based API - Zero-allocation hot paths with ReadOnlySpan<byte>
• PHC string format - Standard format for password hash storage
• SIMD optimized - AVX2 hardware acceleration for block operations
• Parallel lane processing - Multi-threaded hashing for high-security workloads
• Secure memory cleanup - CryptographicOperations.ZeroMemory() for sensitive data
• Multi-target - .NET 8.0, 9.0, 10.0 support

📦 Installation

git clone https://github.com/Paol0B/Argon2id.git
cd Argon2id
dotnet build -c Release

🚀 Quick Start

PHC String Format (Recommended)

using Argon2Sharp;

// Hash password to PHC format string
string phcHash = Argon2PhcFormat.HashToPhcStringWithAutoSalt("MyPassword123");
// Output: $argon2id$v=19$m=19456,t=2,p=1$...salt...$...hash...

// Verify password
var (isValid, parameters) = Argon2PhcFormat.VerifyPhcString("MyPassword123", phcHash);

Basic Hashing

using Argon2Sharp;

// Hash with auto-generated salt
var (hash, salt) = Argon2.HashPasswordWithSalt("MyPassword123");

// Verify with same parameters
var parameters = Argon2Parameters.CreateDefault() with { Salt = salt };
var argon2 = new Argon2(parameters);
bool isValid = argon2.Verify("MyPassword123", hash.AsSpan());

Builder Pattern

using Argon2Sharp;

var parameters = Argon2Parameters.CreateBuilder()
    .WithMemorySizeKB(65536)    // 64 MB
    .WithIterations(4)
    .WithParallelism(4)
    .WithRandomSalt()
    .Build();

var argon2 = new Argon2(parameters);
byte[] hash = argon2.Hash("MyPassword123");

📖 API Reference

Argon2Parameters

Immutable record for hash configuration.

// Factory methods
Argon2Parameters.CreateDefault()       // 19 MB, 2 iterations, 1 parallelism
Argon2Parameters.CreateHighSecurity()  // 64 MB, 4 iterations, 4 parallelism
Argon2Parameters.CreateForTesting()    // 32 KB, 3 iterations (fast, not secure)

// Builder pattern
Argon2Parameters.CreateBuilder()
    .WithType(Argon2Type.Argon2id)
    .WithMemorySizeKB(65536)
    .WithIterations(4)
    .WithParallelism(4)
    .WithHashLength(32)
    .WithSalt(salt)           // Explicit salt
    .WithRandomSalt(16)       // Auto-generate salt
    .WithSecret(key)          // Optional secret key
    .WithAssociatedData(ctx)  // Optional associated data
    .Build();

// Modify with 'with' expression
var modified = parameters with { Salt = newSalt };

Argon2 Class

Main hashing class.

var argon2 = new Argon2(parameters);

// Hash methods
byte[] hash = argon2.Hash("password");
byte[] hash = argon2.Hash(passwordSpan);

// Verify methods
bool valid = argon2.Verify("password", hashSpan);
bool valid = argon2.Verify(passwordSpan, hashSpan);

// Static methods
var (hash, salt) = Argon2.HashPasswordWithSalt("password");
byte[] salt = Argon2.GenerateSalt(16);

Argon2PhcFormat

PHC string format utilities.

// Hash to PHC string
string phc = Argon2PhcFormat.HashToPhcStringWithAutoSalt("password");
string phc = Argon2PhcFormat.HashToPhcString("password", parameters);

// Verify from PHC string
var (isValid, params) = Argon2PhcFormat.VerifyPhcString("password", phcHash);

// Encode/decode
string phc = Argon2PhcFormat.Encode(hash, parameters);
bool ok = Argon2PhcFormat.TryDecode(phc, out hash, out parameters);

Algorithm Types

Parameter Constraints

⚡ Performance

Benchmarks on Intel Core i7-12700H (14 cores), .NET 9.0, AVX2 enabled.

Optimizations

• SIMD/AVX2 - Hardware-accelerated block operations using Vector<ulong>
• Parallel lanes - Multi-threaded processing for p > 1
• Loop unrolling - Fully unrolled Blake2b rounds and permutations
• Aggressive inlining - All hot-path functions inlined
• Hardware intrinsics - Native RotateRight instructions

🧪 Testing

dotnet test

425 unit tests covering:

• RFC 9106 test vectors
• Edge cases and boundary conditions
• PHC format encoding/decoding
• Parameter validation
• Immutability enforcement
• Security and stress tests
• Interoperability tests

📄 License

MIT License - see LICENSE file.