BCryptExtensions 1.0.1

BCryptExtensions

基于 BCrypt.Net-Next 的字符串扩展库，提供简洁的密码哈希与验证 API，并内置灵活的密码强度验证规则。

支持 .NET 8 和 .NET 10。

安装

dotnet add package BCryptExtensions

快速开始

using BCryptExtensions;

// 哈希
var hash = "mypassword".ToBCrypt();
var hash = "mypassword".ToBCrypt(workFactor: 12);

// 验证
bool valid = "mypassword".VerifyBCrypt(hash);

// 增强型哈希与验证
var enhancedHash = "mypassword".ToBCryptEnhanced();
bool validEnhanced = "mypassword".VerifyBCryptEnhanced(enhancedHash);

// 验证 + 自动检测是否需要升级工作因子
if ("mypassword".VerifyBCrypt(storedHash, expectedWorkFactor: 12, out bool needsRehash))
{
    if (needsRehash)
    {
        var newHash = "mypassword".ToBCrypt(12);
        // 持久化 newHash
    }
}

密码验证规则

内置密码强度验证，默认规则：

• 长度 8–20 个字符
• 必须包含 字母、数字、特殊符号 中的 至少两种

基本验证

bool isValid = "P@ssw0rd".ValidatePassword(); // true
bool isValid = "12345678".ValidatePassword(); // false（只有数字）

带错误信息的验证

if (!password.ValidatePassword(out string? error))
{
    Console.WriteLine($"密码不符合要求: {error}");
}
// 输出：密码必须包含字母、数字、特殊符号中的至少两种类型。

一步到位：验证并生成哈希

string? hash = "P@ssw0rd".ToBCryptIfValid();
if (hash != null)
{
    // 保存哈希
}

// 使用自定义工作因子
string? hash = "P@ssw0rd".ToBCryptIfValid(workFactor: 12);

// 增强型
string? hash = "P@ssw0rd".ToBCryptEnhancedIfValid();

自定义验证规则

通过 PasswordValidationOptions 灵活配置验证规则：

预设规则模板

// 默认规则（8-20，至少2种类型）
PasswordValidationOptions.Default

// 严格模式（10-20，至少3种类型）
PasswordValidationOptions.Strict

// 宽松模式（6-30，至少1种类型）
PasswordValidationOptions.Loose

// 不允许符号（仅字母+数字）
PasswordValidationOptions.NoSymbols

使用自定义规则

var options = new PasswordValidationOptions
{
    MinLength = 12,
    MaxLength = 24,
    MinCharTypes = 3,          // 必须包含 3 种类型
    AllowSymbols = true,
    AllowWhitespace = false
};

bool isValid = password.ValidatePassword(options);
bool isValid = password.ValidatePassword(options, out string? error);

// 使用自定义规则生成哈希
string? hash = password.ToBCryptIfValid(options, workFactor: 12);

自定义额外验证（如禁用常见密码）

var options = new PasswordValidationOptions
{
    CustomValidator = (pwd) =>
    {
        var commonPasswords = new[] { "12345678", "password", "qwertyui" };
        if (commonPasswords.Contains(pwd))
            return (false, "密码过于简单，请使用更复杂的密码。");
        return (true, string.Empty);
    }
};

bool isValid = password.ValidatePassword(options, out string? error);

自定义字符分类（如支持中文）

var options = new PasswordValidationOptions
{
    CustomCharTypeClassifier = (ch) =>
    {
        if (char.IsLetter(ch) || IsChineseChar(ch))
            return CharType.Letter;
        if (char.IsDigit(ch))
            return CharType.Digit;
        if (char.IsSymbol(ch) || char.IsPunctuation(ch))
            return CharType.Symbol;
        return CharType.Other;
    }
};

完整 API 一览

BCrypt 哈希与验证

密码验证

验证 + 哈希（组合方法）

PasswordValidationOptions 配置项

许可证

MIT