BCrypt.Net 使用详细教程

概述

什么是 BCrypt？

BCrypt 是一种基于 Blowfish 密码的密码哈希算法，专门设计用于安全地存储用户密码。它通过可配置的"工作因子"（work factor）来增加计算成本，使暴 力 破 解变得极其耗时。BCrypt 会自动生成盐值（salt），并将其嵌入到哈希结果中，确保每次哈希都是唯一的。

BCrypt.Net 简介

BCrypt.Net 是 BCrypt 算法在 .NET 平台上的实现库，由 BCrypt.Net 团队开发和维护。它提供了简洁易用的 API，支持密码哈希、验证、自定义工作因子等核心功能。该库完全托管代码（managed code），无外部依赖，可运行于 Windows、Linux 和 macOS 平台。

核心特性

• 自适应哈希：工作因子可调整，抵御硬件升级带来的破解能力提升
• 自动盐值生成：每次哈希都自动生成唯一的盐值
• 兼容性强：兼容原版 BCrypt 算法，可与 PHP、Python、Java 等语言互操作
• 简单 API：易于集成到现有项目中
• 线程安全：可在多线程环境下安全使用

安装

NuGet 包管理器

通过 NuGet 安装是最推荐的方式。在 Visual Studio 的包管理器控制台中执行以下命令：

Install-Package BCrypt.Net-NET

基础用法

密码哈希

最基本的用法是将明文密码转换为安全的哈希值：

using BCrypt.Net;

// 生成密码哈希
string password = "MySecurePassword123";
string hash = BCrypt.Net.BCrypt.HashPassword(password);

Console.WriteLine($"哈希结果: {hash}");

生成的哈希字符串格式为：\$2a\$12$xxxx...，其中：

• \$2a$ 表示 BCrypt 算法版本
• 12 表示工作因子（迭代次数为 2^12 = 4096 次）
• 后续为盐值和哈希值

密码验证

验证用户输入的密码是否正确：

string password = "MySecurePassword123";
string hash = BCrypt.Net.BCrypt.HashPassword(password);

// 验证正确密码
bool isValid = BCrypt.Net.BCrypt.Verify(password, hash);
Console.WriteLine($"密码验证: {isValid}");  // 输出: True

// 验证错误密码
bool isInvalid = BCrypt.Net.BCrypt.Verify("WrongPassword", hash);
Console.WriteLine($"错误密码验证: {isInvalid}");  // 输出: False

完整示例：用户注册与登录

public class UserService
{
    // 用户注册时哈希密码
    public string RegisterUser(string username, string password)
    {
        // 哈希密码，默认工作因子为 11
        string passwordHash = BCrypt.Net.BCrypt.HashPassword(password);
        
        // 将 hash 存入数据库
        // SaveUserToDatabase(username, passwordHash);
        
        return passwordHash;
    }
    
    // 用户登录时验证密码
    public bool ValidateUser(string username, string password)
    {
        // 从数据库获取存储的哈希值
        string storedHash = GetStoredHash(username);
        
        if (string.IsNullOrEmpty(storedHash))
            return false;
        
        // 验证密码
        return BCrypt.Net.BCrypt.Verify(password, storedHash);
    }
    
    private string GetStoredHash(string username)
    {
        // 数据库查询逻辑
        return "从数据库获取的哈希值";
    }
}

高级特性

自定义工作因子

工作因子直接决定哈希的计算成本。工作因子每增加 1，计算时间翻倍。根据安全需求和服务器性能选择合适的值：

csharp

// 使用默认工作因子 11（约 200ms）
string hash1 = BCrypt.Net.BCrypt.HashPassword(password);

// 使用更高的工作因子 12（约 400ms）
string hash2 = BCrypt.Net.BCrypt.HashPassword(password, EnhancedEntropy: false, workFactor: 12);

// 使用较低的工作因子 10（约 100ms）
string hash3 = BCHash.Net.BCrypt.HashPassword(password, workFactor: 10);

盐值管理

BCrypt.Net 自动为每个密码生成唯一的盐值，无需手动管理。但如果需要自定义盐值：

// 生成自定义盐值
string salt = BCrypt.Net.BCrypt.GenerateSalt();

// 使用自定义盐值哈希密码
string hash = BCrypt.Net.BCrypt.HashPassword(password, salt);

// 也可以使用扩展方法
string hash2 = password.Hash(workFactor: 12);

盐值验证

如果需要在不重新哈希的情况下验证盐值格式：

string hash = "\$2a\$12$XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

// 检查哈希格式是否有效
bool isValidFormat = BCrypt.Net.BCrypt.IsHashString(hash);

枚举类型选项

BCrypt.Net 提供了类型安全的枚举选项：

// 启用增强熵
string hash1 = BCrypt.Net.BCrypt.HashPassword(
    password,
    EnhancedEntropy: true
);

// 使用特定的 BCrypt 变体
string hash2 = BCrypt.Net.BCrypt.HashPassword(
    password,
    hashType: BCrypt.Net.HashType.SHA256
);

// 验证时指定哈希版本
bool isValid = BCrypt.Net.BCrypt.Verify(
    password,
    hash,
    hashPrefix: BCrypt.Net.HashPrefix.Hashes2A
);

安全最佳实践

工作因子选择

工作因子的选择需要平衡安全性和用户体验：

工作因子	迭代次数	估计耗时	建议场景
10	1024	~100ms	性能敏感场景
11	2048	~200ms	推荐默认值
12	4096	~400ms	高安全需求
13	8192	~800ms	极高安全需求

重要提示：工作因子应随硬件性能提升而定期增加。建议每 2-3 年评估一次，必要时提高工作因子。

安全存储

存储哈希时需要注意以下几点：

// 1. 不要记录原始密码
// ❌ 错误做法
Log($"User logged in with password: {password}");

// ✅ 正确做法
Log($"User login attempt for: {username}");

// 2. 哈希值存储安全
string hash = BCrypt.Net.BCrypt.HashPassword(password);
// hash 应加密存储或存放在安全的配置中

// 3. 定期轮换密钥
// 如果系统使用外部加密密钥，应定期轮换

防时序攻击

BCrypt.Net 的 Verify 方法默认使用常数时间比较，防止时序攻击（timing attack）。无需额外处理。

防止暴 力 破 解

在登录接口实现速率限制和账户锁定机制：

public class LoginService
{
    private Dictionary<string, int> _failedAttempts = new();
    private const int MaxAttempts = 5;
    private const int LockoutMinutes = 15;
    
    public LoginResult Authenticate(string username, string password)
    {
        // 检查账户是否被锁定
        if (IsAccountLocked(username))
        {
            return LoginResult.AccountLocked;
        }
        
        // 验证密码
        bool isValid = BCrypt.Net.BCrypt.Verify(password, GetStoredHash(username));
        
        if (!isValid)
        {
            RecordFailedAttempt(username);
            return LoginResult.InvalidPassword;
        }
        
        ClearFailedAttempts(username);
        return LoginResult.Success;
    }
    
    private bool IsAccountLocked(string username)
    {
        if (!_failedAttempts.ContainsKey(username))
            return false;
        
        var lastAttempt = _failedAttempts[username];
        return lastAttempt >= MaxAttempts;
    }
    
    private void RecordFailedAttempt(string username)
    {
        _failedAttempts.TryGetValue(username, out int count);
        _failedAttempts[username] = count + 1;
    }
    
    private void ClearFailedAttempts(string username)
    {
        _failedAttempts.Remove(username);
    }
}

最低密码策略

在哈希之前验证密码强度：

public bool ValidatePasswordStrength(string password)
{
    if (string.IsNullOrEmpty(password) || password.Length < 8)
        return false;
    
    // 检查是否包含数字
    if (!password.Any(char.IsDigit))
        return false;
    
    // 检查是否包含字母
    if (!password.Any(char.IsLetter))
        return false;
    
    return true;
}

常见应用场景

ASP.NET Core 集成

在 ASP.NET Core 中集成 BCrypt.Net 进行密码管理：

csharp

// Services/PasswordService.cs
public class PasswordService
{
    private const int DefaultWorkFactor = 11;
    
    public string HashPassword(string password)
    {
        return BCrypt.Net.BCrypt.HashPassword(password, workFactor: DefaultWorkFactor);
    }
    
    public bool VerifyPassword(string password, string hash)
    {
        return BCrypt.Net.BCrypt.Verify(password, hash);
    }
    
    // 升级旧哈希（当工作因子需要提高时）
    public string UpgradePasswordHash(string password, string oldHash)
    {
        if (!BCrypt.Net.BCrypt.NeedsRehash(oldHash, workFactor: DefaultWorkFactor))
            return oldHash;
        
        if (!BCrypt.Net.BCrypt.Verify(password, oldHash))
            return null;
        
        return HashPassword(password);
    }
}

// Program.cs 或 Startup.cs
builder.Services.AddSingleton<PasswordService>();

Entity Framework Core 集成

在 EF Core 中使用 BCrypt.Net 处理用户密码：

// Models/User.cs
public class User
{
    public int Id { get; set; }
    public string Username { get; set; }
    public string PasswordHash { get; set; }
    public DateTime CreatedAt { get; set; }
}

// Data/ApplicationDbContext.cs
public class ApplicationDbContext : DbContext
{
    public DbSet<User> Users { get; set; }
}

// Services/UserService.cs
public class UserService
{
    private readonly ApplicationDbContext _context;
    private readonly PasswordService _passwordService;
    
    public async Task<User> CreateUserAsync(string username, string password)
    {
        var user = new User
        {
            Username = username,
            PasswordHash = _passwordService.HashPassword(password),
            CreatedAt = DateTime.UtcNow
        };
        
        _context.Users.Add(user);
        await _context.SaveChangesAsync();
        
        return user;
    }
    
    public async Task<bool> ValidateCredentialsAsync(string username, string password)
    {
        var user = await _context.Users
            .FirstOrDefaultAsync(u => u.Username == username);
        
        if (user == null)
            return false;
        
        return _passwordService.VerifyPassword(password, user.PasswordHash);
    }
}

性能与调优

性能基准测试

测量不同工作因子的性能表现：

csharp

public void BenchmarkBCrypt()
{
    string password = "TestPassword123!";
    int[] workFactors = { 10, 11, 12, 13 };
    
    foreach (int workFactor in workFactors)
    {
        var sw = System.Diagnostics.Stopwatch.StartNew();
        
        for (int i = 0; i < 100; i++)
        {
            BCrypt.Net.BCrypt.HashPassword(password, workFactor: workFactor);
        }
        
        sw.Stop();
        double avgMs = sw.Elapsed.TotalMilliseconds / 100;
        Console.WriteLine($"WorkFactor {workFactor}: 平均 {avgMs:F2}ms");
    }
}

典型测试结果（实际环境可能有差异）：

工作因子	单次哈希耗时	100 次总耗时
10	~100ms	~10s
11	~200ms	~20s
12	~400ms	~40s
13	~800ms	~80s

异步操作

对于大量密码哈希操作，使用异步方法避免阻塞：

csharp

public async Task<string> HashPasswordAsync(string password)
{
    return await Task.Run(() => 
        BCrypt.Net.BCrypt.HashPassword(password));
}

public async Task<bool> VerifyPasswordAsync(string password, string hash)
{
    return await Task.Run(() => 
        BCrypt.Net.BCrypt.Verify(password, hash));
}

批量处理

处理大量用户密码迁移时：

public async Task MigratePasswordsAsync(IEnumerable<User> users)
{
    int batchSize = 100;
    var userList = users.ToList();
    
    for (int i = 0; i < userList.Count; i += batchSize)
    {
        var batch = userList.Skip(i).Take(batchSize);
        
        await Task.WhenAll(batch.Select(async user =>
        {
            // 验证旧密码格式并重新哈希
            string newHash = BCrypt.Net.BCrypt.HashPassword(user.OldPassword);
            await UpdateUserHashAsync(user.Id, newHash);
        }));
        
        Console.WriteLine($"已处理 {Math.Min(i + batchSize, userList.Count)}/{userList.Count}");
    }
}

缓存策略

对于需要频繁验证的场景，可以考虑缓存策略：

public class CachedPasswordService
{
    private readonly PasswordService _innerService;
    private readonly IMemoryCache _cache;
    private readonly TimeSpan _cacheDuration = TimeSpan.FromMinutes(5);
    
    public CachedPasswordService(PasswordService innerService, IMemoryCache cache)
    {
        _innerService = innerService;
        _cache = cache;
    }
    
    public bool VerifyPassword(string password, string hash, string userId)
    {
        string cacheKey = $"pwd_verify_{userId}_{hash}";
        
        return _cache.GetOrCreate(cacheKey, entry =>
        {
            entry.AbsoluteExpirationRelativeToNow = _cacheDuration;
            return _innerService.VerifyPassword(password, hash);
        });
    }
}

故障排除

常见错误与解决方案

哈希格式错误

csharp

// 问题：哈希字符串格式不完整
string incompleteHash = "invalid";

// 解决：验证哈希格式
bool isValid = BCrypt.Net.BCrypt.IsHashString(incompleteHash);
if (!isValid)
{
    Console.WriteLine("哈希格式无效，需要重新生成");
}

工作因子不匹配

csharp

// 问题：数据库中存储的哈希使用旧的工作因子
string oldHash = "\$2a\$10$...";  // 工作因子为 10

// 解决：使用 NeedsRehash 检查
bool needsUpgrade = BCrypt.Net.BCrypt.NeedsRehash(oldHash, workFactor: 11);
if (needsUpgrade)
{
    // 用户下次登录时升级哈希
}

密码验证失败

public bool SafeVerifyPassword(string password, string hash)
{
    try
    {
        return BCrypt.Net.BCrypt.Verify(password, hash);
    }
    catch (SaltParseException ex)
    {
        // 处理盐值解析错误
        Logger.LogError(ex, "哈希格式解析失败");
        return false;
    }
    catch (HashInformationException ex)
    {
        // 处理哈希信息错误
        Logger.LogError(ex, "哈希信息无效");
        return false;
    }
}

调试技巧

启用详细日志以便排查问题：

public void DebugBCryptOperations()
{
    string password = "TestPassword";
    
    // 生成哈希并打印详细信息
    string hash = BCrypt.Net.BCrypt.HashPassword(password, workFactor: 11);
    
    Console.WriteLine($"原始哈希: {hash}");
    Console.WriteLine($"盐值部分: {hash.Substring(0, 29)}");
    Console.WriteLine($"哈希部分: {hash.Substring(29)}");
    
    // 验证
    bool result = BCrypt.Net.BCrypt.Verify(password, hash);
    Console.WriteLine($"验证结果: {result}");
    
    // 检查工作因子
    int detectedWorkFactor = BCrypt.Net.BCrypt.DetectWorkFactor(hash);
    Console.WriteLine($"检测到的工作因子: {detectedWorkFactor}");
}

实践方案

using System.Security.Cryptography;
using System.Text;

namespace PMS.Common.Helper
{
    /// <summary>
    /// 密码加密帮助类
    /// 使用BCrypt算法进行密码哈希加密，支持盐值自动生成
    /// </summary>
    public class EncryptHelper
    {
        /// <summary>
        /// BCrypt工作因子，越大越安全但越慢，默认11
        /// </summary>
        private const int WorkFactor = 11;

        /// <summary>
        /// 对密码进行BCrypt哈希加密
        /// </summary>
        /// <param name="password">原始密码</param>
        /// <returns>加密后的密码哈希</returns>
        public static string HashPassword(string password)
        {
            if (string.IsNullOrEmpty(password))
            {
                throw new ArgumentNullException(nameof(password), "密码不能为空");
            }
            return BCrypt.Net.BCrypt.HashPassword(password, WorkFactor);
        }

        /// <summary>
        /// 验证密码是否正确
        /// </summary>
        /// <param name="password">原始密码</param>
        /// <param name="hash">加密后的密码哈希</param>
        /// <returns>验证是否通过</returns>
        public static bool VerifyPassword(string password, string hash)
        {
            if (string.IsNullOrEmpty(password) || string.IsNullOrEmpty(hash))
            {
                return false;
            }
            try
            {
                return BCrypt.Net.BCrypt.Verify(password, hash);
            }
            catch
            {
                return false;
            }
        }

        /// <summary>
        /// 使用MD5对字符串进行哈希（适用于非密码场景）
        /// </summary>
        /// <param name="input">输入字符串</param>
        /// <returns>MD5哈希值（小写）</returns>
        public static string MD5Hash(string input)
        {
            if (string.IsNullOrEmpty(input))
            {
                return string.Empty;
            }

            using var md5 = MD5.Create();
            var inputBytes = Encoding.UTF8.GetBytes(input);
            var hashBytes = md5.ComputeHash(inputBytes);
            
            var sb = new StringBuilder();
            foreach (var b in hashBytes)
            {
                sb.Append(b.ToString("x2"));
            }
            return sb.ToString();
        }

        /// <summary>
        /// 生成随机盐值
        /// </summary>
        /// <param name="length">盐值长度</param>
        /// <returns>随机盐值字符串</returns>
        public static string GenerateSalt(int length = 16)
        {
            var bytes = new byte[length];
            using var rng = RandomNumberGenerator.Create();
            rng.GetBytes(bytes);
            return Convert.ToBase64String(bytes);
        }
    }
}