> ## 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 的 vsql_crypto 扩展

> vsql_crypto 扩展把 pgcrypto 函数集带到 MySQL：哈希、HMAC 签名、AES 加密、密码哈希和安全随机数据。

`vsql_crypto` 为 MySQL 带来一组与 `pgcrypto` 兼容的函数，基于 OpenSSL
构建。它覆盖四项工作：对值做哈希、对载荷签名、加密列，以及存储一个
以后可以验证的密码。

| | |
| - | - |
| **维护者** | VillageSQL |
| **源代码和完整文档** | [villagesql/vsql-crypto](https://github.com/villagesql/vsql-crypto) |
| **许可证** | GPL-2.0 |

## 安装

如果您使用安装脚本、Docker 镜像或发行版压缩包安装了 VillageSQL，
`vsql_crypto.veb` 已经位于服务器的 `lib/veb/` 目录中。
用一条语句将它安装到服务器中：

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

确认它已存在：

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_crypto';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_crypto    |
+----------------+
```

要自行构建，请按照[存储库](https://github.com/villagesql/vsql-crypto)中的
构建说明进行操作。

## 新增内容

| 函数 | 返回 | 作用 |
| - | - | - |
| `digest(data, algorithm)` | 二进制 | 用 `md5`、`sha1`、`sha224`、`sha256`、`sha384` 或 `sha512` 对数据做哈希 |
| `hmac(data, key, algorithm)` | 二进制 | 用带密钥的哈希对数据签名 |
| `encrypt(data, key, type)` | 二进制 | 用 AES 加密 |
| `decrypt(data, key, type)` | 二进制 | 用同一密钥还原 `encrypt` 的结果 |
| `crypt(password, salt)` | 文本 | 把密码哈希为一个自带参数的字符串 |
| `gen_salt(type, iterations)` | 文本 | 为 `crypt` 生成盐，仅支持 `pbkdf2-sha256` 和 `pbkdf2-sha512` |
| `gen_random_bytes(n)` | 二进制 | 密码学安全的随机字节 |
| `gen_random_uuid()` | 文本 | 以文本形式返回的随机版本 4 UUID |
| `crypto_version()` | 文本 | 扩展所链接的 OpenSSL 版本 |

标为二进制的函数返回原始字节，因此请用 `HEX()` 包装后再读取。
其余函数返回文本。

## 示例

对载荷签名：

```sql theme={null}
SET @secret = 'shared-key';
SELECT HEX(hmac('{"order":4711}', @secret, 'sha256')) AS signature;
```

```
+------------------------------------------------------------------+
| signature                                                        |
+------------------------------------------------------------------+
| 7261870227EF8090041AB514536550671974770FCE19416ABB634C55389C3141 |
+------------------------------------------------------------------+
```

存储密码。结果自带算法、迭代次数和盐，因此验证时不需要在旁边额外
保存任何东西：

```sql theme={null}
SELECT crypt('correct horse battery', gen_salt('pbkdf2-sha256', 100000)) AS hash;
```

```
+------------------------------------------------------------------------------------------+
| hash                                                                                     |
+------------------------------------------------------------------------------------------+
| $pbkdf2-sha256$100000$N6MXcYhD7SS4DS9sVhaQag$rv6zFwkwfo4N8+lgEpU5/LR4mOLtio04b6iKCSRlF5E |
+------------------------------------------------------------------------------------------+
```

您的盐是随机的，因此每次调用得到的哈希都不同。

> [!NOTE]
>
> `gen_salt` 仅支持 `pbkdf2-sha256` 和 `pbkdf2-sha512`。请求 `bf`、`md5` 或 `des`
> 会返回 NULL，而盐为 NULL 时 `crypt` 也返回 NULL，因此由 `pgcrypto`
> 写入的 bcrypt 哈希无法在这里验证。

## 另请参阅

* [在 MySQL 中对数据做哈希](https://villagesql.com/docs/en/guides/hashing-data.md) — 使用哪种算法以及存储什么
* [用 HMAC 对载荷签名](https://villagesql.com/docs/en/guides/hmac-mysql.md) — webhook 签名和令牌验证
* [加密列](https://villagesql.com/docs/en/guides/encrypting-columns.md) — 密钥处理，以及加密不能保护什么
* [安装扩展](https://villagesql.com/docs/zh/extensions/install.md) — `INSTALL EXTENSION` 如何工作，以及服务器在哪里查找包
* [可用扩展](https://villagesql.com/docs/zh/extensions/catalog) — 完整目录
* [villagesql/vsql-crypto](https://github.com/villagesql/vsql-crypto) — 源代码、构建说明和已知限制


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