PasswordPolicy 2.1.1

Random Password Generator

A .NET library that generates random passwords using upper-case letters, lower-case letters, numbers, and special characters. You can configure the generator to match your password policy, including required character counts, excluded characters, included special characters, and unique character requirements.

Supported Frameworks

• .NET Standard 2.0
• .NET 8
• .NET 9
• .NET 10

Security

Password generation uses RandomNumberGenerator for cryptographically secure random numbers. Generated characters and shuffling use bounded random values to avoid modulo bias. The library also supports entropy requirements, blocked password deny lists, repeat limits, and readable password generation.

Default Policy

The default policy generates a random password with these rules. You can override them by creating your own Policy.

• Minimum Password length : 4
• Maximum Password length : 6

If any minimum character count is set to 0, that character type is not required. If all minimum counts are 0, the generator uses any available character from the configured character sets.

• Minimum Lower Case Chars : 1
• Minimum Upper Case Chars : 1
• Minimum Numeric Chars : 1
• Minimum Special Chars : 1

Usage

using PasswordGenerator;

using IPasswordPolicy passwordPolicy = new PasswordPolicy();

RandomSecurePassword password = passwordPolicy.Generate();

Console.WriteLine(password.GetPasswordStrength());
Console.WriteLine(passwordPolicy.IsValid(password.SecurePassword));

Custom Policy

using PasswordGenerator;

public sealed class StrongPolicy : Policy
{
    public override int MinimumPasswordLength => 16;
    public override int MaximumPasswordLength => 20;
    public override int MinimumLowerCaseChars => 4;
    public override int MinimumUpperCaseChars => 4;
    public override int MinimumNumericChars => 3;
    public override int MinimumSpecialChars => 3;
}

using IPasswordPolicy passwordPolicy = new PasswordPolicy(new StrongPolicy());

string password = passwordPolicy.Generate().SecurePassword;

You can also create policies without deriving from Policy.

var policy = Policy.Create(
    minimumPasswordLength: 16,
    maximumPasswordLength: 20,
    minimumLowerCaseChars: 4,
    minimumUpperCaseChars: 4,
    minimumNumericChars: 3,
    minimumSpecialChars: 3,
    minimumEntropyBits: 95,
    disallowRepeatedAdjacentChars: true,
    maximumRepeatedChars: 3);

using IPasswordPolicy passwordPolicy = new PasswordPolicy(policy);

Built-In Preset Policies

The library includes lightweight preset policies for common use cases.

using IPasswordPolicy defaultPolicy = new PasswordPolicy(Policy.Default);
using IPasswordPolicy strongPolicy = new PasswordPolicy(Policy.Strong);
using IPasswordPolicy pinPolicy = new PasswordPolicy(Policy.Pin);
using IPasswordPolicy readablePolicy = new PasswordPolicy(
    chars => chars.ExcludeAmbiguousChars(),
    Policy.Readable);

• Policy.Default: Balanced default password policy.
• Policy.Strong: Longer passwords with minimum entropy and repeat protection.
• Policy.Pin: Numeric PIN generation.
• Policy.Readable: Good base policy for human-readable passwords.
• Policy.Passphrase: Recommended policy marker for passphrase use cases.

Exclude Ambiguous Characters

Use ExcludeAmbiguousChars() when passwords may be read, typed, or shared manually. It removes characters commonly confused with each other, such as 0, O, 1, I, l, i, and o.

using PasswordGenerator;

using IPasswordPolicy passwordPolicy = new PasswordPolicy(
    chars => chars.ExcludeAmbiguousChars(),
    Policy.Default);

string readablePassword = passwordPolicy.Generate().SecurePassword;

You can combine it with existing include and exclude options.

using IPasswordPolicy passwordPolicy = new PasswordPolicy(
    chars => chars
        .ExcludeAmbiguousChars()
        .ExcludeLowerChars("aeu")
        .IncludeSpecialChars("@#$%"),
    Policy.Default);

Generate Multiple Passwords

Use GenerateMany(count) when you need a batch of passwords from the same policy.

using PasswordGenerator;

using IPasswordPolicy passwordPolicy = new PasswordPolicy();

List<RandomSecurePassword> passwords = passwordPolicy.GenerateMany(10);

Passphrase Generation

Use GeneratePassphrase() when users need a strong password that is easier to type manually.

using PasswordGenerator;

using IPasswordPolicy passwordPolicy = new PasswordPolicy(Policy.Passphrase);

RandomSecurePassword passphrase = passwordPolicy.GeneratePassphrase();

You can tune the passphrase output.

var options = new PassphraseOptions
{
    WordCount = 8,
    Separator = "-",
    IncludeNumber = true,
    MinimumEntropyBits = 50,
    WordList = new[] { "alpha", "bravo", "charlie", "delta", "ember", "forest", "granite", "harbor" }
};

RandomSecurePassword passphrase = passwordPolicy.GeneratePassphrase(options);

When WordList is omitted, the built-in lightweight word list is used.

Entropy Requirement

Use MinimumEntropyBits to require a minimum estimated entropy score.

var policy = Policy.Create(
    minimumPasswordLength: 16,
    maximumPasswordLength: 24,
    minimumLowerCaseChars: 4,
    minimumUpperCaseChars: 4,
    minimumNumericChars: 3,
    minimumSpecialChars: 3,
    minimumEntropyBits: 95);

using IPasswordPolicy passwordPolicy = new PasswordPolicy(policy);

You can also estimate entropy directly.

double bits = PasswordEntropy.EstimateBits("Example-Password-123!");

Blocked Password Validation

Use blockedPasswords to reject common, leaked, or application-specific passwords.

var policy = Policy.Create(
    minimumPasswordLength: 8,
    maximumPasswordLength: 32,
    minimumLowerCaseChars: 0,
    minimumUpperCaseChars: 0,
    minimumNumericChars: 0,
    minimumSpecialChars: 0,
    blockedPasswords: new[] { "password", "password123", "admin123" });

using IPasswordPolicy passwordPolicy = new PasswordPolicy(policy);

bool isValid = passwordPolicy.IsValid("password123"); // false

Repeat Protection

Use repeat protection to reject passwords with repeated adjacent characters or too many copies of the same character.

var policy = Policy.Create(
    minimumPasswordLength: 10,
    maximumPasswordLength: 20,
    disallowRepeatedAdjacentChars: true,
    maximumRepeatedChars: 2);

using IPasswordPolicy passwordPolicy = new PasswordPolicy(policy);

Async Unique Password Generation

Use RenderUniquePasswordAsync when uniqueness must be checked against a database, cache, or external service.

string password = await passwordPolicy.RenderUniquePasswordAsync(async generatedPassword =>
{
    return await userRepository.PasswordExistsAsync(generatedPassword);
}, maxAttempt: 5);

The callback should return true when the generated password already exists and a new attempt is required.

Tests

This repository includes an xUnit test project:

dotnet test PasswordGenerator.Tests/PasswordGenerator.Tests.csproj

The tests cover strong policy generation, ambiguous character exclusion, batch generation, passphrases, blocked passwords, repeat rules, and async unique password generation.

Performance Project

This repository includes a lightweight performance console project with no external benchmark dependencies.

dotnet build PasswordGenerator.Performance/PasswordGenerator.Performance.csproj -c Release
dotnet run -c Release --no-build --project PasswordGenerator.Performance/PasswordGenerator.Performance.csproj

You can pass custom iteration counts when you want a longer run:

dotnet run -c Release --no-build --project PasswordGenerator.Performance/PasswordGenerator.Performance.csproj -- 10000 500 100000 250000

Arguments are [passwordIterations] [batchIterations] [validationIterations] [entropyIterations].

The performance project measures:

• Default password generation
• Strong policy password generation
• Readable password generation with ambiguous characters excluded
• Batch generation
• Passphrase generation
• Strong password validation
• Entropy estimation

Performance And Package Design

The project stays lightweight by using only the .NET base class library. There are no runtime package dependencies. Password generation uses StringBuilder, bounded cryptographic random numbers, and small in-memory policy checks. XML documentation is generated during build for public APIs that include documentation comments.

Authors

Nilesh

Donate