Argon2Sharp 1.0.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. Built with .NET 9 and designed for security-critical applications.

Features • Installation • Quick Start • Documentation • Benchmarks • Contributing

</div>

✨ Features

<table> <tr> <td>

🎯 Algorithm Support

• Argon2d (data-dependent)
• Argon2i (data-independent)
• Argon2id (hybrid - recommended)

</td> <td>

⚡ Performance

• Zero-allocation paths
• Span<T> optimizations
• Parallel processing support

</td> </tr> <tr> <td>

🔒 Security

• RFC 9106 compliant
• Constant-time comparisons
• Automatic memory cleanup

</td> <td>

🛠️ Developer Experience

• Simple & advanced APIs
• PHC string format support
• Comprehensive documentation

</td> </tr> </table>

Key Highlights

📦 Installation

Via Git Clone

git clone https://github.com/Paol0B/Argon2id.git
cd Argon2id
dotnet build Argon2Sharp/Argon2Sharp.csproj

Build from Source

# Build in Release mode
dotnet build -c Release

# Run tests
dotnet test

# Run examples
dotnet run --project Argon2Sharp.Examples

Requirements

• .NET 9.0 SDK or later
• C# 12 compatible compiler

🚀 Quick Start

Basic Password Hashing

using Argon2Sharp;

// Hash a password with default parameters (Argon2id, 19MB, 2 iterations)
byte[] hash = Argon2.HashPassword("MyPassword123", out byte[] salt);

// Verify password
var parameters = Argon2Parameters.CreateDefault();
parameters.Salt = salt;
var argon2 = new Argon2(parameters);
bool isValid = argon2.Verify("MyPassword123", hash);  // ✅ true

Using PHC String Format (Recommended)

using Argon2Sharp;

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

// Verify password (constant-time comparison)
bool isValid = Argon2PhcFormat.VerifyPassword("MyPassword123", phcHash);  // ✅ true

📖 Documentation

Advanced Usage

<details> <summary><b>Custom Parameters</b></summary>

using Argon2Sharp;

var parameters = new Argon2Parameters
{
    Type = Argon2Type.Argon2id,        // Algorithm variant
    MemorySizeKB = 65536,               // 64 MB
    Iterations = 4,                     // Time cost
    Parallelism = 4,                    // Threads
    HashLength = 32,                    // Output size
    Salt = Argon2.GenerateSalt(16)     // 16-byte salt
};

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

</details>

<details> <summary><b>High Security Configuration</b></summary>

using Argon2Sharp;

// Use high security preset (64MB, 4 iterations, 4 threads)
var parameters = Argon2Parameters.CreateHighSecurity();
parameters.Salt = Argon2.GenerateSalt(16);

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

</details>

<details> <summary><b>With Secret Key and Associated Data</b></summary>

using Argon2Sharp;
using System.Text;

var parameters = new Argon2Parameters
{
    Type = Argon2Type.Argon2id,
    MemorySizeKB = 32768,
    Iterations = 3,
    Parallelism = 4,
    HashLength = 32,
    Salt = Argon2.GenerateSalt(16),
    Secret = Encoding.UTF8.GetBytes("app-secret-key"),
    AssociatedData = Encoding.UTF8.GetBytes("user-context")
};

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

</details>

Algorithm Variants

💡 Recommendation: Use Argon2id for password hashing (RFC 9106 recommendation)

Parameter Guidelines

Recommended for Password Hashing (RFC 9106)

// ... other parameters

};

**Best for:** Cryptocurrency mining, KDF where side-channels aren't a concern

## Parameter Guidelines

### Recommended for Password Hashing (RFC 9106)

```csharp
var parameters = new Argon2Parameters
{
    Type = Argon2Type.Argon2id,
    MemorySizeKB = 19456,      // 19 MB (minimum recommended)
    Iterations = 2,             // 2 passes (minimum recommended)
### Parameter Guidelines

#### Recommended for Password Hashing (RFC 9106)

```csharp
var parameters = new Argon2Parameters
{
    Type = Argon2Type.Argon2id,
    MemorySizeKB = 19456,      // 19 MB (minimum recommended)
    Iterations = 2,             // 2 passes (minimum recommended)
    Parallelism = 1,            // Single-threaded
    HashLength = 32             // 256-bit output
};

Parameter Constraints

⚡ Performance

Benchmarks on Intel Core i7 (typical modern CPU):

💡 Tip: Adjust parameters based on your threat model and available resources. Higher values = better security but slower performance.

🧪 Testing

# Run all tests
dotnet test

# Run with detailed output
dotnet test --verbosity detailed

# Run specific test class
dotnet test --filter "FullyQualifiedName~Argon2Rfc9106Tests"

Test Coverage

• ✅ 34 unit tests covering all algorithm variants
• ✅ RFC 9106 test vectors validation
• ✅ Edge cases and parameter validation
• ✅ PHC format encoding/decoding
• ✅ 95%+ code coverage

🏗️ Architecture

Argon2 Class

Main class for hashing operations.

public sealed class Argon2
{
    public Argon2(Argon2Parameters parameters);
    
    public byte[] Hash(string password);
    public byte[] Hash(byte[] password);
    public void Hash(ReadOnlySpan<byte> password, Span<byte> output);
    
    public bool Verify(string password, byte[] hash);
    public bool Verify(byte[] password, byte[] hash);
    
    public static byte[] HashPassword(string password, out byte[] salt);
    public static bool VerifyPassword(string password, byte[] hash, byte[] salt, ...);
    public static byte[] GenerateSalt(int length = 16);
## 🏗️ Architecture

Argon2Sharp/ ├── Core/ │ ├── Blake2b.cs # Blake2b-512 hash implementation │ ├── Argon2Core.cs # Core compression & permutation functions │ └── Argon2Engine.cs # Main algorithm orchestration ├── Argon2.cs # Public API interface ├── Argon2Parameters.cs # Configuration & presets ├── Argon2Types.cs # Type & version enumerations └── Argon2PhcFormat.cs # PHC string encoding/decoding

### Key Components

- **Blake2b**: Pure C# implementation of Blake2b-512 for internal hashing
- **Argon2Core**: Low-level block operations with G function and P permutation
- **Argon2Engine**: Memory initialization, block filling, and finalization
- **Memory Management**: Efficient pooling with `ArrayPool<T>` and automatic cleanup

## 📚 API Reference

<details>
<summary><b>Argon2 Class</b></summary>

Main class for hashing operations.

```csharp
public sealed class Argon2
{
    public Argon2(Argon2Parameters parameters);
    
    // Hash methods
    public byte[] Hash(string password);
    public byte[] Hash(byte[] password);
    public void Hash(ReadOnlySpan<byte> password, Span<byte> output);
    
    // Verify methods (constant-time comparison)
    public bool Verify(string password, byte[] hash);
    public bool Verify(byte[] password, byte[] hash);
    
    // Static convenience methods
    public static byte[] HashPassword(string password, out byte[] salt);
    public static bool VerifyPassword(string password, byte[] hash, byte[] salt, ...);
    public static byte[] GenerateSalt(int length = 16);
    public static string ToBase64(byte[] hash);
    public static byte[] FromBase64(string base64Hash);
}

</details>

<details> <summary><b>Argon2Parameters Class</b></summary>

Configuration parameters for Argon2.

public sealed class Argon2Parameters
{
    public Argon2Type Type { get; set; }
    public Argon2Version Version { get; set; }
    public int MemorySizeKB { get; set; }
    public int Iterations { get; set; }
    public int Parallelism { get; set; }
    public int HashLength { get; set; }
    public byte[]? Salt { get; set; }
    public byte[]? Secret { get; set; }
    public byte[]? AssociatedData { get; set; }
    
    // Factory methods
    public static Argon2Parameters CreateDefault();        // 19MB, 2 iterations
    public static Argon2Parameters CreateHighSecurity();   // 64MB, 4 iterations
    public static Argon2Parameters CreateForTesting();     // 32KB, 3 iterations
    
    public void Validate();
    public Argon2Parameters Clone();
}

</details>

<details> <summary><b>Argon2PhcFormat Class</b></summary>

PHC string format encoding/decoding.

public static class Argon2PhcFormat
{
    public static string Encode(byte[] hash, byte[] salt, Argon2Type type, ...);
    public static bool TryDecode(string phcString, out byte[]? hash, out byte[]? salt, ...);
    public static string HashPassword(string password, int memorySizeKB = 19456, ...);
    public static bool VerifyPassword(string password, string phcHash);
}

PHC Format:

$argon2id$v=19$m=19456,t=2,p=1$base64salt$base64hash

</details>

🔒 Security Considerations

Best Practices

✅ DO:

• Use Argon2id for password hashing (recommended by RFC 9106)
• Generate cryptographically random salts using Argon2.GenerateSalt()
• Store salt alongside the hash (they're not secret)
• Use PHC string format for easy storage and portability
• Tune parameters based on your threat model and available resources
• Use constant-time comparison (built into Verify methods)

❌ DON'T:

• Reuse salts across different passwords
• Use predictable salts (timestamps, user IDs, etc.)
• Store passwords in plain text (obviously!)
• Use insufficient memory or iterations for production
• Ignore parameter validation errors

Parameter Tuning Guide

// Low security (testing only) - NOT for production
var testParams = Argon2Parameters.CreateForTesting();  // 32KB, 3 iterations

// Moderate security (minimum recommended)
var defaultParams = Argon2Parameters.CreateDefault();  // 19MB, 2 iterations

// High security (sensitive applications)
var highSecParams = Argon2Parameters.CreateHighSecurity();  // 64MB, 4 iterations

// Custom tuning
var customParams = new Argon2Parameters
{
    Type = Argon2Type.Argon2id,
    MemorySizeKB = 131072,  // 128 MB
    Iterations = 5,          // 5 passes
    Parallelism = 8,         // 8 threads
    HashLength = 64          // 512-bit output
};

Threat Model Considerations

🤝 Contributing

Contributions are welcome! Please ensure:

• ✅ Code follows C# coding conventions and .NET 9 best practices
• ✅ All tests pass (dotnet test)
• ✅ New features include comprehensive tests
• ✅ XML documentation is updated
• ✅ README is updated for significant changes

Development Setup

# Clone repository
git clone https://github.com/Paol0B/Argon2id.git
cd Argon2id

# Build
dotnet build

# Run tests
dotnet test

# Run examples
dotnet run --project Argon2Sharp.Examples

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Based on the Argon2 specification by Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich
• Follows RFC 9106 - Argon2 Memory-Hard Function for Password Hashing
• Implements RFC 7693 - BLAKE2 Cryptographic Hash

📖 References

• RFC 9106 - Argon2 Memory-Hard Function
• RFC 7693 - BLAKE2 Cryptographic Hash
• Argon2 Official GitHub
• OWASP Password Storage Cheat Sheet

🌟 Star History

<div align="center">

Made with ❤️ by Paolo

If you find this project useful, please consider giving it a ⭐!

Report Bug • Request Feature • Documentation

</div>