PasswordGenerator 3.0.0

Password Generator

A cross-platform .NET library that generates cryptographically secure random passwords, passphrases, OTPs, API keys and readable identifiers. Configure it with a fluent API, ready-made presets (OWASP/NIST) or dependency injection — with async support and entropy estimation.

NuGet

Install via NuGet: Install-Package PasswordGenerator

Or click here to go to the package landing page

It targets net8.0 and net10.0, so it requires .NET 8 or later. If you need to run on .NET Framework or other older runtimes, use the 2.x line (which targets netstandard2.0).

Upgrading from 2.x? See the v2 → v3 migration guide. The v2 API still works; the one behavioural change is that invalid settings now throw (or use TryNext) instead of returning an error string as the "password".

Basic usage

The examples below assume using PasswordGenerator; (and, for the dependency-injection section, using Microsoft.Extensions.DependencyInjection;).

// By default, all character types are available and the length is 16.
// Returns a random password with the default settings.
var pwd = new Password();
var password = pwd.Next();

// Set the length. Must be between 4 and 256.
// Returns a password that is 32 characters long.
var pwd = new Password(32);
var password = pwd.Next();

// Choose which character types to include.
// Returns a 21-character password of lowercase and uppercase letters only.
var pwd = new Password(includeLowercase: true, includeUppercase: true, includeNumeric: false, includeSpecial: false, passwordLength: 21);
var password = pwd.Next();

Fluent usage

// Build up your requirements by chaining, e.g. .IncludeNumeric()
// Returns a numbers-only password with the default length of 16.
var pwd = new Password().IncludeNumeric();
var password = pwd.Next();

// Combine lower, upper and special characters the same way.
var pwd = new Password().IncludeLowercase().IncludeUppercase().IncludeSpecial();
var password = pwd.Next();

// As above, but with a length of 128.
var pwd = new Password(128).IncludeLowercase().IncludeUppercase().IncludeSpecial();
var password = pwd.Next();

// As above, but passing the length via LengthRequired().
var pwd = new Password().IncludeLowercase().IncludeUppercase().IncludeSpecial().LengthRequired(128);
var password = pwd.Next();

// Specify your own special characters.
var pwd = new Password().IncludeLowercase().IncludeUppercase().IncludeNumeric().IncludeSpecial("[]{}^_=");
var password = pwd.Next();

Presets

Ready-made starting points; later fluent calls still override them. See the standards mapping for the OWASP/NIST rationale.

string strong  = Password.ForOwasp().Next();            // full printable-ASCII pool, length 16
string nist    = Password.ForNist().Next();             // NIST-aligned, length 12
string otp     = Password.ForOtp(6).Next();             // 6-digit one-time code
string apiKey  = Password.ForApiKey(32).Next();         // URL-safe token
string envName = Password.ForEnvironmentName(12).Next();// readable id, no look-alike characters
string phrase  = Password.ForPassphrase(4).Next();      // e.g. "maple-river-quartz-bloom-42"
string strongPhrase = Password.ForPassphraseWithEntropy(80).Next(); // word count derived to clear 80 bits
string memorable = Password.ForMemorable().Next();      // capitalized, ~80+ bits, e.g. "Maple-River-Quartz-Bloom-Glade-Vivid-42"

ForPassphraseWithEntropy(targetBits) derives the word count needed to reach the target and enforces it as a floor. You can also pass minimumEntropyBits to ForPassphrase(...) to reject configurations that are too weak.

For sites that require a digit and a symbol, pass includeSymbol: true. A random symbol is attached to one randomly chosen word (e.g. maple-river#-quartz-bloom-42), so the phrase passes composition rules while staying memorable.

To omit the separator entirely, pass separator: null (or an empty string when binding from configuration); the words are concatenated directly, e.g. Password.ForPassphrase(4, separator: null).Next() → "mapleriverquartzbloom42". This does not change the passphrase's entropy — the separator is a fixed character and never contributes to strength — it only affects readability.

Quality controls

// Remove look-alike characters (I l 1 O 0 o)
var readable = new Password(20).ExcludeAmbiguous().Next();

// Guarantee at least N characters from a class.
// CharacterClass values: Lowercase, Uppercase, Numeric, Special.
var pwd = new Password(16).RequireAtLeast(CharacterClass.Numeric, 2).Next();

// Use a custom pool, or every printable ASCII character
var custom = new Password().WithCharacters("ABCDEF0123456789").LengthRequired(24).Next();
var ascii  = new Password().WithAllAscii().LengthRequired(40).Next();

// Estimate strength in bits
double bits = new Password(20).EstimateEntropyBits();

Error handling

// Next() throws ArgumentException when the settings can't produce a valid password.
var password = new Password(16).Next();

// TryNext() never throws; it returns false on invalid settings.
if (new Password(16).TryNext(out var result))
    Console.WriteLine(result);

Async and batches

Generate(count) returns a batch synchronously; the Async overloads return a ValueTask and honour a CancellationToken. The parameterless Generate() returns DefaultBatchCount passwords (1 by default; set the property to change it).

async Task ExampleAsync(CancellationToken cancellationToken)
{
    var pwd = new Password(16);

    string password            = await pwd.NextAsync(cancellationToken);
    IReadOnlyList<string> ten  = pwd.Generate(10);
    IReadOnlyList<string> ten2 = await pwd.GenerateAsync(10, cancellationToken);
}

Dependency injection

// Register once (optionally bind from appSettings.json)
services.AddPasswordGenerator(o =>
{
    o.Length = 20;
    o.IncludeSpecial = true;
    o.ExcludeAmbiguous = true;
});

// Inject IPasswordGenerator wherever you need it
public class SignupService(IPasswordGenerator generator)
{
    public string NewTempPassword() => generator.Next();
}

To register a passphrase generator instead, set the Passphrase options (or bind a Passphrase section from configuration):

services.AddPasswordGenerator(o =>
    o.Passphrase = new PassphraseOptions { WordCount = 6, Capitalize = true });

You can also bind from appSettings.json (code configuration still takes precedence over bound values, which in turn take precedence over the defaults):

{
  "PasswordGenerator": {
    "Length": 20,
    "IncludeSpecial": true,
    "ExcludeAmbiguous": true,
    "DefaultBatchCount": 5
  }
}

services.AddPasswordGenerator(config.GetSection("PasswordGenerator"));

Documentation

• v2 → v3 migration guide
• Changelog
• Design & architecture docs

License & attribution

PasswordGenerator is licensed under the MIT License.

Passphrases are generated from the EFF Large Wordlist (7,776 words) by the Electronic Frontier Foundation, used under the Creative Commons Attribution 3.0 US license. See THIRD-PARTY-NOTICES.md for details.