> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 MySQL 中进行密码哈希

> 为什么 MySQL 内置的哈希函数用于密码并不安全，以及如何在 VillageSQL 中使用 PBKDF2 正确地存储密码哈希。

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

MySQL 提供了 `MD5()` 和 `SHA2()`。开发者在哈希密码时常常会直接使用它们。这是一个错误——这些函数的设计目标是速度快，而这恰恰是密码存储最不需要的特性。

## 为什么快速哈希不适合密码

MD5 和 SHA-256 这类加密哈希函数是为速度优化的。一块现代 GPU 每秒可以计算数十亿次 SHA-256 哈希。这对校验和与数据完整性很有用。但对于密码而言，这意味着攻击者一旦拿到您的密码哈希表，几小时内就能暴力破解。

密码哈希算法——bcrypt、Argon2、PBKDF2——是有意设计得很慢的。它们的设计目标是让校验一个密码耗时数十毫秒，这对登录来说完全可以接受，却让暴力破解变得不切实际。

```sql theme={null}
-- Don't do this
INSERT INTO users (email, password_hash)
VALUES ('user@example.com', SHA2('mypassword', 256));
```

## 标准答案：在应用代码中哈希

大多数 MySQL 应用通过在应用层哈希来正确处理这个问题——在 PHP、Python、Node.js 或任何运行该应用的语言中使用 `bcrypt`。数据库只会看到哈希后的值。

这种做法可行，但它造成了一种分裂：哈希逻辑位于应用代码中，而数据位于数据库中。迁移、批量操作和数据导入都必须经过应用才能正确哈希，否则就得在多个代码库中重复实现哈希逻辑。

## 使用 VillageSQL：直接在 SQL 中使用 PBKDF2

VillageSQL 的 `vsql_crypto` 扩展添加了 `crypt()` 和 `gen_salt()`——一套基于 PBKDF2 的密码哈希 API，仿照 PostgreSQL 的 pgcrypto 设计。您可以直接在 SQL 中哈希和验证密码，而无需经过应用代码。

```sql theme={null}
INSTALL EXTENSION vsql_crypto;
```

### 存储密码

```sql theme={null}
CREATE TABLE users (
    user_id       INT PRIMARY KEY AUTO_INCREMENT,
    email         VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL
);

-- gen_salt generates a random salt; the second argument is iteration count
-- Higher iterations = slower hash = harder to brute-force
INSERT INTO users (email, password_hash)
VALUES ('user@example.com', crypt('mypassword', gen_salt('pbkdf2-sha256', 10000)));
```

`gen_salt` 只支持 PBKDF2 系列——`pbkdf2-sha256` 和 `pbkdf2-sha512`，以及更短的别名 `pbkdf2`、`sha256` 和 `sha512`。pgcrypto 的 `bf`（bcrypt）、`md5` 和 `des` 类型不受支持：对这些名称，`gen_salt` 返回 NULL。

### 验证密码

`crypt()` 会自动从存储的哈希中提取盐和参数——您只需将存储的哈希作为第二个参数传入：

```sql theme={null}
-- Returns TRUE if the password matches, FALSE otherwise
SELECT crypt('mypassword', password_hash) = password_hash AS is_valid
FROM users
WHERE email = 'user@example.com';
```

### 选择迭代次数

迭代次数控制计算哈希所需的时间。迭代越多 = 越慢 = 越难暴力破解，但登录也会越慢。

| 迭代次数 | 每次哈希的大致耗时 | 建议 |
| :- | :- | :- |
| 1,000 | \< 1ms | 太快——不要用于密码 |
| 10,000 | \~5ms | 生产环境的最低要求 |
| 100,000 | \~50ms | 更好——NIST 对 PBKDF2-SHA256 的建议值 |
| 600,000 | \~300ms | OWASP 2023 的建议值 |

从 10,000 开始，并在硬件允许的范围内逐步提高。您的登录端点可以承受 100ms；而尝试数十亿次猜测的攻击者承受不起。

```sql theme={null}
-- More secure: 100,000 iterations
INSERT INTO users (email, password_hash)
VALUES ('user@example.com', crypt('mypassword', gen_salt('pbkdf2-sha256', 100000)));
```

## 何时在 SQL 中哈希，何时在应用代码中哈希

在 SQL 中哈希并不总是正确的选择。在以下情况使用它：

* 您在进行批量插入或迁移，经过应用并不现实
* 您希望哈希逻辑集中在数据库层
* 您在构建由 SQL 驱动的管理工具或种子脚本

在以下情况在应用代码中哈希：

* 您的应用框架已经有经过充分测试的 bcrypt/Argon2 库
* 您使用的语言拥有成熟的加密生态（大多数语言都是如此）
* 您希望在不进行模式迁移的情况下更换哈希算法

两种方式都能产生安全的哈希。关键在于使用慢速算法——PBKDF2、bcrypt 或 Argon2——而不是原始的 SHA2。

## 常见问题

#### PBKDF2 和 bcrypt 一样强吗？

在相同的迭代次数下，bcrypt 略有优势，因为它是内存困难型的（在 GPU 上更难并行化）。高迭代次数（100,000 以上）的 PBKDF2 仍然很强，并被广泛部署。这种差异在对抗性场景中才有意义；两者都远优于 SHA2。

#### 我可以迁移现有的 SHA2 哈希吗？

可以。添加一个 `needs_rehash` 标志。在登录成功时，检查哈希是否为旧的 SHA2 格式，并用 `crypt()` 重新哈希。等所有活跃用户都登录过之后，删除旧哈希。

#### 我可以迁移 PostgreSQL 中现有的 bcrypt 哈希吗？

不能直接迁移。对于任何非 PBKDF2 格式的盐或哈希，`crypt()` 都返回 NULL，因此来自 pgcrypto 的 bcrypt 哈希在这里无法验证。将它们保留在现有列中，并在每个用户下次成功登录时重新哈希，方法与上面的 SHA2 哈希相同。[PostgreSQL 到 MySQL 迁移指南](https://villagesql.com/docs/zh/guides/postgres-to-mysql.md)提供了完整的扩展映射。

#### 存储的哈希包含盐吗？

包含。`crypt()` 的输出将算法、迭代次数、盐和哈希编码在一个字符串中。您不需要单独管理盐。

## 故障排除

| 问题 | 解决方案 |
| :- | :- |
| `FUNCTION <database>.crypt does not exist` | 运行 `INSTALL EXTENSION vsql_crypto` |
| 验证始终返回 FALSE | 确保您将存储的哈希（而不是新的盐）作为 `crypt()` 的第二个参数传入 |
| 哈希输出为 NULL | 检查 `crypt()` 的两个参数均不为 NULL，且盐参数是 PBKDF2 的盐或哈希——对于 bcrypt、`md5` 和 `des` 值，`crypt()` 返回 NULL |

## 另请参阅

* [在 MySQL 中哈希数据](https://villagesql.com/docs/zh/guides/hashing-data.md)——用于完整性校验和去重的非密码哈希
* [MySQL 中的对称加密](https://villagesql.com/docs/zh/guides/symmetric-encryption.md)——何时加密（而非哈希）才是正确的选择
* [在 MySQL 中生成随机数据](https://villagesql.com/docs/zh/guides/random-data-mysql.md)——生成加密安全的盐和令牌


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.