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

版本 8.4

9.0
8.0

8.0 日语

MySQL 8.4 参考手册 / ... / 使用 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 插件需要使用 HTTPS 协议安全连接到 HashiCorp Vault 服务器。典型的设置包括一组证书和密钥文件

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) 的文件。密钥是随机生成的 RSA 密钥，分别为 4,096 位和 2,048 位。
每个命令都会提示输入密码。出于测试目的，不需要密码。要禁用它，请省略 -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`	否

为了在服务器启动过程中可用，必须使用 --early-plugin-load 选项加载 keyring_hashicorp。如上表所示，几个与插件相关的系统变量是必需的，也必须设置。例如，在服务器 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_ 系统变量设置为 “未提交”，布尔值变量设置为 OFF。如果插件无法连接但之前存在连接，则该连接将保持活动状态，并且 _commit_ 变量将反映用于该连接的值。

注意

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

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