Simple.PasswordGenerator

---

🚀 Overview

Simple.PasswordGenerator is a lightweight, secure password generator for .NET applications.
It creates cryptographically strong passwords based on customizable policies — including length, required character types, special characters, and the ability to exclude ambiguous characters for better readability.

No dependencies beyond .NET. Simple to integrate, flexible to configure, and safe to use.

---

🔑 Key Features

• 🔐 Cryptographically secure password generation
• ⚙️ Fully customizable policies (length, uppercase, lowercase, digits, special chars, ambiguous character exclusion)
• 🎯 Default policy with sensible security defaults
• 🔄 Supports configuration via lambda or predefined policy objects
• 🧩 Provides password strength estimation including entropy calculation
• 🔀 Uses Fisher–Yates shuffle for password character randomization
• 🧩 Compatible with .NET 8 and later

---

📚 Table of Contents

1. Getting Started
   • Installing
   • Basic Usage
   • Advanced Usage
   • Generating Password with Strength Info
2. Examples
3. Technical Information
4. Known Issues & Limitations
5. Contributing
6. License

---

🚦 Getting Started

Use Simple.PasswordGenerator to generate strong, policy-compliant passwords easily.

📦 Installing

Add the package via NuGet:

dotnet add package Simple.PasswordGenerator

---

🧪 Basic Usage

var generator = new PasswordGenerator();
var password = generator.Generate();
Console.WriteLine($"Generated password: {password}");

---

🎯 Advanced Usage

Configure a custom password policy using a lambda:

var password = generator.Generate(policy =>
{
    policy.Length = 20;
    policy.RequireSpecial = false;
    policy.RequireDigit = true;
    policy.RequireUppercase = true;
    policy.RequireLowercase = true;
    policy.ExcludeAmbiguousCharacters = true;
});

Or generate using a predefined PasswordPolicy object:

var policy = new PasswordPolicy
{
    Length = 12,
    RequireSpecial = true,
    RequireDigit = true,
    RequireUppercase = false,
    RequireLowercase = true,
    SpecialCharacters = "@#$",
    ExcludeAmbiguousCharacters = true,
    AmbiguousCharacters = "O0Il1"
};
var passwordFromPolicy = generator.Generate(policy);

---

📊 Generating Password with Strength Info

You can generate a password and receive detailed strength information including entropy and strength category:

var strengthResult = generator.GenerateWithStrength(policy =>
{
    policy.Length = 16;
    policy.RequireUppercase = true;
    policy.RequireLowercase = true;
    policy.RequireDigit = true;
    policy.RequireSpecial = true;
});

Console.WriteLine($"Password: {strengthResult.Password}");
Console.WriteLine($"Entropy (bits): {strengthResult.EntropyBits}");
Console.WriteLine($"Strength: {strengthResult.Strength}");

---

🖼️ Examples

using Simple.PasswordGenerator;

var passwordGenerator = new PasswordGenerator();

// Default policy password
var defaultPassword = passwordGenerator.Generate();
Console.WriteLine($"Default policy password: {defaultPassword}");

// Custom policy via lambda
var customPassword = passwordGenerator.Generate(policy =>
{
    policy.Length = 20;
    policy.RequireSpecial = false;
    policy.RequireDigit = true;
    policy.RequireUppercase = true;
    policy.RequireLowercase = true;
    policy.ExcludeAmbiguousCharacters = true;
});
Console.WriteLine($"Custom policy password: {customPassword}");

// Using a PasswordPolicy instance
var policyInstance = new PasswordPolicy
{
    Length = 12,
    RequireSpecial = true,
    RequireDigit = true,
    RequireUppercase = false,
    RequireLowercase = true,
    SpecialCharacters = "@#$",
    ExcludeAmbiguousCharacters = true,
    AmbiguousCharacters = "O0Il1"
};
var policyPassword = passwordGenerator.Generate(policyInstance);
Console.WriteLine($"Password from policy instance: {policyPassword}");

// Generate password with strength info
var strengthResult = passwordGenerator.GenerateWithStrength(policy =>
{
    policy.Length = 16;
    policy.RequireUppercase = true;
    policy.RequireLowercase = true;
    policy.RequireDigit = true;
    policy.RequireSpecial = true;
});
Console.WriteLine($"Password: {strengthResult.Password}");
Console.WriteLine($"Entropy (bits): {strengthResult.EntropyBits}");
Console.WriteLine($"Strength: {strengthResult.Strength}");

---

🔬 Technical Information

• Uses System.Security.Cryptography.RandomNumberGenerator for cryptographically secure randomization
• Password policy validation ensures minimum length and required character types
• Supports exclusion of ambiguous characters (e.g., 'O', '0', 'I', 'l', '1') to improve password readability
• Character categories: uppercase, lowercase, digits, special characters, and additional custom characters
• Password characters are shuffled with the Fisher–Yates algorithm for unpredictability
• Provides entropy calculation and password strength classification based on entropy

---

🐞 Known Issues & Limitations

• No known issues at this time

---

🤝 Contributing

Bug reports, feature requests, and pull requests are welcome!
Please open an issue or submit a PR via GitHub Issues.

---

📄 License

This project is licensed under the MIT License.