MySQL :: MySQL 9.0 参考手册 :: 8.4.4.8 使用 HashiCorp Vault 密钥环插件

版本 9.0

8.4 当前
8.0

8.0 日语

MySQL 9.0 参考手册 / ... / 使用 HashiCorp Vault 密钥环插件

8.4.4.8 使用 HashiCorp Vault 密钥环插件

注意

keyring_hashicorp 插件是 MySQL 企业版（商业产品）中包含的扩展。要了解有关商业产品的更多信息，请参见 https://www.mysqlserver.cn/products/.

keyring_hashicorp 密钥环插件与 HashiCorp Vault 进行通信以进行后端存储。该插件支持 HashiCorp Vault AppRole 身份验证。密钥信息不会永久存储在 MySQL 服务器本地存储中。（可选的内存中密钥缓存可以用作中间存储。）随机密钥生成在 MySQL 服务器端执行，随后将密钥存储到 HashiCorp Vault。

keyring_hashicorp 插件支持构成标准 MySQL 密钥环服务接口的函数。这些函数执行的密钥环操作可在两个级别访问

SQL 接口：在 SQL 语句中，调用第 8.4.4.12 节，“通用密钥环密钥管理功能” 中描述的函数。
C 接口：在 C 语言代码中，调用第 7.6.9.2 节，“密钥环服务” 中描述的密钥环服务函数。

示例（使用 SQL 接口）

SELECT keyring_key_generate('MyKey', 'AES', 32);
SELECT keyring_key_remove('MyKey');

有关 keyring_hashicorp 允许的密钥值的特征的信息，请参见第 8.4.4.10 节，“支持的密钥环密钥类型和长度”。

要安装 keyring_hashicorp，请使用第 8.4.4.3 节，“密钥环插件安装” 中找到的一般说明，以及此处找到的特定于 keyring_hashicorp 的配置信息。特定于插件的配置包括准备连接到 HashiCorp Vault 所需的证书和密钥文件，以及配置 HashiCorp Vault 本身。以下部分提供了必要的说明。

证书和密钥准备

keyring_hashicorp 插件需要与 HashiCorp Vault 服务器建立安全连接，使用 HTTPS 协议。典型设置包括一组证书和密钥文件

company.crt：属于该组织的自定义 CA 证书。此文件既由 HashiCorp Vault 服务器使用，也由 keyring_hashicorp 插件使用。
vault.key：HashiCorp Vault 服务器实例的私钥。此文件由 HashiCorp Vault 服务器使用。
vault.crt：HashiCorp Vault 服务器实例的证书。此文件必须由组织 CA 证书签名。

以下说明描述了如何使用 OpenSSL 创建证书和密钥文件。（如果您已经拥有这些文件，请继续执行 HashiCorp Vault 设置。）所示说明适用于 Linux 平台，可能需要针对其他平台进行调整。

重要

通过这些说明生成的证书是自签名的，这可能不是很安全。在您获得使用此类文件的经验后，请考虑从注册的证书颁发机构获取证书/密钥材料。

准备公司和 HashiCorp Vault 服务器密钥。
使用以下命令生成密钥文件
```
openssl genrsa -aes256 -out company.key 4096
openssl genrsa -aes256 -out vault.key 2048
```
这些命令会生成包含公司私钥 (company.key) 和 Vault 服务器私钥 (vault.key) 的文件。这些密钥分别是随机生成的 4,096 位和 2,048 位 RSA 密钥。
每个命令都会提示输入密码。出于测试目的，不需要密码。要禁用它，请省略 -aes256 参数。
密钥文件包含敏感信息，应存储在安全位置。密码（同样敏感）稍后需要，因此请将其写下并存储在安全位置。
（可选）要检查密钥文件的内容和有效性，请使用以下命令
```
openssl rsa -in company.key -check
openssl rsa -in vault.key -check
```
创建公司 CA 证书。
使用以下命令创建一个名为 company.crt 的公司 CA 证书文件，该文件有效期为 365 天（在单行上输入命令）
```
openssl req -x509 -new -nodes -key company.key
  -sha256 -days 365 -out company.crt
```
如果您在密钥生成期间使用 -aes256 参数执行密钥加密，则在创建 CA 证书时会提示您输入公司密钥密码。还会提示您输入有关证书持有人（即您或您的公司）的信息，如下所示
```
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:
```
使用适当的值回答提示。
创建证书签名请求。
要创建 HashiCorp Vault 服务器证书，必须为新创建的服务器密钥准备证书签名请求 (CSR)。创建一个名为 request.conf 的配置文件，其中包含以下行。如果 HashiCorp Vault 服务器不在本地主机上运行，请替换相应的 CN 和 IP 值，并进行其他必要的更改。
```
[req]
distinguished_name = vault
x509_entensions = v3_req
prompt = no

[vault]
C = US
ST = CA
L = RWC
O = Company
CN = 127.0.0.1

[v3_req]
subjectAltName = @alternatives
authorityKeyIdentifier = keyid,issuer
basicConstraints = CA:TRUE

[alternatives]
IP = 127.0.0.1
```
使用此命令创建签名请求
```
openssl req -new -key vault.key -config request.conf -out request.csr
```
输出文件（request.csr）是一个中间文件，用作创建服务器证书的输入。
创建 HashiCorp Vault 服务器证书。
使用公司证书（company.crt）对来自 HashiCorp Vault 服务器密钥（vault.key）和 CSR（request.csr）的组合信息进行签名，以创建 HashiCorp Vault 服务器证书（vault.crt）。使用以下命令执行此操作（在单行上输入命令）
```
openssl x509 -req -in request.csr
  -CA company.crt -CAkey company.key -CAcreateserial
  -out vault.crt -days 365 -sha256
```
要使 vault.crt 服务器证书可用，请将 company.crt 公司证书的内容附加到它。这是必需的，以便公司证书在请求中与服务器证书一起交付。
```
cat company.crt >> vault.crt
```
如果您显示 vault.crt 文件的内容，它应该看起来像这样
```
-----BEGIN CERTIFICATE-----
... content of HashiCorp Vault server certificate ...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... content of company certificate ...
-----END CERTIFICATE-----
```

HashiCorp Vault 设置

以下说明描述了如何创建 HashiCorp Vault 设置，以促进测试 keyring_hashicorp 插件。

重要

测试设置类似于生产设置，但 HashiCorp Vault 的生产使用需要额外的安全注意事项，例如使用非自签名证书并将公司证书存储在系统信任存储中。您必须实施满足您的操作要求所需的任何其他安全步骤。

这些说明假定可以访问在证书和密钥准备中创建的证书和密钥文件。如果您没有这些文件，请参阅该部分。

获取 HashiCorp Vault 二进制文件。
从 https://www.vaultproject.io/downloads.html 下载适合您平台的 HashiCorp Vault 二进制文件。
解压缩存档的内容以生成可执行文件 vault 命令，该命令用于执行 HashiCorp Vault 操作。如有必要，将安装命令的目录添加到系统路径。
（可选）HashiCorp Vault 支持自动完成选项，使操作更轻松。有关更多信息，请参阅 https://learn.hashicorp.com/vault/getting-started/install#command-completion.

创建 HashiCorp Vault 服务器配置文件。

准备一个名为 config.hcl 的配置文件，内容如下。对于 tls_cert_file、tls_key_file 和 path 值，请替换适合您系统的路径名。

listener "tcp" {
  address="127.0.0.1:8200"
  tls_cert_file="/home/username/certificates/vault.crt"
  tls_key_file="/home/username/certificates/vault.key"
}

storage "file" {
  path = "/home/username/vaultstorage/storage"
}

ui = true

启动 HashiCorp Vault 服务器。
要启动 Vault 服务器，请使用以下命令，其中 -config 选项指定刚创建的配置文件的路径
```
vault server -config=config.hcl
```
在此步骤中，系统可能会提示您输入存储在 vault.key 文件中的 Vault 服务器私钥的密码。
服务器应该启动，并在控制台上显示一些信息（IP、端口等）。
为了能够输入剩余的命令，请将 vault server 命令放到后台或在继续之前打开另一个终端。
初始化 HashiCorp Vault 服务器。

注意

此步骤中描述的操作仅在首次启动 Vault 时才需要，以获取解封密钥和根令牌。后续的 Vault 实例重启仅需要使用解封密钥进行解封。

发出以下命令（假设使用 Bourne shell 语法）
```
export VAULT_SKIP_VERIFY=1
vault operator init -n 1 -t 1
```
第一个命令使 vault 命令能够暂时忽略系统信任存储中没有添加公司证书的事实。它弥补了我们的自签名 CA 未添加到该存储的事实。（对于生产使用，应添加此类证书。）
第二个命令创建一个单个解封密钥，并要求存在单个解封密钥才能进行解封。（对于生产使用，实例将具有多个解封密钥，最多需要输入这些密钥中的那么多密钥才能解封它。解封密钥应交付给公司内的密钥保管人。使用单个密钥可能会被视为安全问题，因为它允许通过单个密钥保管人解封保管库。）
Vault 应该回复有关解封密钥和根令牌的信息，以及一些其他文本（实际的解封密钥和根令牌值与这里显示的值不同）
```
...
Unseal Key 1: I2xwcFQc892O0Nt2pBiRNlnkHzTUrWS+JybL39BjcOE=
Initial Root Token: s.vTvXeo3tPEYehfcd9WH7oUKz
...
```
将解封密钥和根令牌存储在安全位置。
解封 HashiCorp Vault 服务器。
使用此命令解封 Vault 服务器
```
vault operator unseal
```
当提示您输入解封密钥时，请使用之前在 Vault 初始化期间获得的密钥。
Vault 应该生成输出，表明设置已完成并且保管库已解封。
登录到 HashiCorp Vault 服务器并验证其状态。
准备以 root 身份登录所需的環境變數
```
vault login s.vTvXeo3tPEYehfcd9WH7oUKz
```
对于该命令中的令牌值，请替换之前在 Vault 初始化期间获得的根令牌的内容。
验证 Vault 服务器状态
```
vault status
```
输出应该包含以下行（以及其他行）
```
...
Initialized     true
Sealed          false
...
```
设置 HashiCorp Vault 身份验证和存储。

注意

此步骤中描述的操作仅在首次运行 Vault 实例时需要。它们不需要在之后重复。

启用 AppRole 身份验证方法并验证它是否在身份验证方法列表中
```
vault auth enable approle
vault auth list
```
启用 Vault KeyValue 存储引擎
```
vault secrets enable -version=1 kv
```
创建并设置一个角色，以便与 keyring_hashicorp 插件一起使用（在单行上输入命令）
```
vault write auth/approle/role/mysql token_num_uses=0
  token_ttl=20m token_max_ttl=30m secret_id_num_uses=0
```
添加 AppRole 安全策略。

注意

此步骤中描述的操作仅在首次运行 Vault 实例时需要。它们不需要在之后重复。

准备一个策略，允许之前创建的角色访问相应的秘密。创建一个名为 mysql.hcl 的新文件，内容如下
```
path "kv/mysql/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
```
注意

本例中的 kv/mysql/ 可能需要根据您的本地安装策略和安全要求进行调整。如果是这样，请在这些说明中其他出现 kv/mysql/ 的地方进行相同的调整。

将策略文件导入 Vault 服务器以创建一个名为 mysql-policy 的策略，然后将该策略分配给新角色
```
vault policy write mysql-policy mysql.hcl
vault write auth/approle/role/mysql policies=mysql-policy
```
获取新创建角色的 ID 并将其存储在安全位置
```
vault read auth/approle/role/mysql/role-id
```
为该角色生成一个秘密 ID 并将其存储在安全位置
```
vault write -f auth/approle/role/mysql/secret-id
```
在生成这些 AppRole 角色 ID 和秘密 ID 凭据后，预计它们会无限期有效。它们不需要再次生成，并且 keyring_hashicorp 插件可以使用它们进行持续配置。有关 AuthRole 身份验证的更多信息，请访问 https://www.vaultproject.io/docs/auth/approle.html.

keyring_hashicorp 配置

插件库文件包含 keyring_hashicorp 插件和一个可加载函数 keyring_hashicorp_update_config()。当插件初始化和终止时，它会自动加载和卸载该函数。无需手动加载和卸载该函数。

keyring_hashicorp 插件支持下表中显示的配置参数。要指定这些参数，请将值分配给相应的系统变量。

配置参数	系统变量	强制
HashiCorp 服务器 URL	`keyring_hashicorp_server_url`	否
AppRole 角色 ID	`keyring_hashicorp_role_id`	是
AppRole 秘密 ID	`keyring_hashicorp_secret_id`	是
存储路径	`keyring_hashicorp_store_path`	是
授权路径	`keyring_hashicorp_auth_path`	否
CA 证书文件路径	`keyring_hashicorp_ca_path`	否
缓存控制	`keyring_hashicorp_caching`	否

要在服务器启动过程中可用， keyring_hashicorp 必须使用 --early-plugin-load 选项加载。如上表所示，几个与插件相关的系统变量是强制性的，也必须设置。例如，在服务器 my.cnf 文件中使用以下行，根据需要调整您的平台的 .so 后缀和文件位置

[mysqld]
early-plugin-load=keyring_hashicorp.so
keyring_hashicorp_role_id='ee3b495c-d0c9-11e9-8881-8444c71c32aa'
keyring_hashicorp_secret_id='0512af29-d0ca-11e9-95ee-0010e00dd718'
keyring_hashicorp_store_path='/v1/kv/mysql'
keyring_hashicorp_auth_path='/v1/auth/approle/login'

注意

根据 HashiCorp 文档，所有 API 路由都以协议版本为前缀（您可以在前面的示例中看到，如 /v1/ 在 keyring_hashicorp_store_path 和 keyring_hashicorp_auth_path 值中）。如果 HashiCorp 开发了新的协议版本，则可能需要将 /v1/ 更改为配置中的其他内容。

MySQL 服务器使用 AppRole 身份验证针对 HashiCorp Vault 进行身份验证。成功身份验证需要向 Vault 提供两个秘密，即角色 ID 和秘密 ID，它们在概念上类似于用户名和密码。要使用的角色 ID 和秘密 ID 值是在之前执行的 HashiCorp Vault 设置过程中获得的。要指定这两个 ID，请将它们各自的值分配给 keyring_hashicorp_role_id 和 keyring_hashicorp_secret_id 系统变量。设置过程还会生成一个 /v1/kv/mysql 的存储路径，它是分配给 keyring_hashicorp_commit_store_path 的值。

在插件初始化时， keyring_hashicorp 尝试使用配置值连接到 HashiCorp Vault 服务器。如果连接成功，插件会将这些值存储在名称中包含 _commit_ 的相应系统变量中。例如，连接成功后，插件会将 keyring_hashicorp_role_id 和 keyring_hashicorp_store_path 的值存储在 keyring_hashicorp_commit_role_id 和 keyring_hashicorp_commit_store_path 中。

可以在 keyring_hashicorp_update_config() 函数的帮助下在运行时执行重新配置

使用 SET 语句将所需的新值分配给上表中显示的配置系统变量。这些赋值本身对正在进行的插件操作没有影响。
调用 keyring_hashicorp_update_config() 以使插件使用新的变量值重新配置并重新连接到 HashiCorp Vault 服务器。
如果连接成功，插件会将更新后的配置值存储在名称中包含 _commit_ 的相应系统变量中。

例如，如果您已将 HashiCorp Vault 重新配置为侦听端口 8201 而不是默认端口 8200，请像这样重新配置 keyring_hashicorp

mysql> SET GLOBAL keyring_hashicorp_server_url = 'https://127.0.0.1:8201';
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT keyring_hashicorp_update_config();
+--------------------------------------+
| keyring_hashicorp_update_config()    |
+--------------------------------------+
| Configuration update was successful. |
+--------------------------------------+
1 row in set (0.03 sec)

如果插件在初始化或重新配置期间无法连接到 HashiCorp Vault 且没有现有连接，则 _commit_ 系统变量将被设置为字符串值变量的 'Not committed'，以及布尔值变量的 OFF。如果插件无法连接但存在现有连接，则该连接将保持活动状态，并且 _commit_ 变量将反映用于该连接的值。

注意

如果在服务器启动时未设置强制性系统变量，或如果发生其他插件初始化错误，则初始化将失败。在这种情况下，您可以使用运行时重新配置过程来初始化插件，而无需重新启动服务器。

有关 keyring_hashicorp 插件特定系统变量和函数的更多信息，请参见第 8.4.4.16 节，“Keyring 系统变量” 和第 8.4.4.13 节，“插件特定 Keyring 密钥管理函数”。