6.4.4.10 使用 HashiCorp Vault 密钥环插件

MySQL 8.0 参考手册 / 第 4 章 MySQL 程序 / 4.6 管理和实用程序 / 4.6.8 mysql_migrate_keyring — 密钥环密钥迁移实用程序 / 6.4.4.10 使用 HashiCorp Vault 密钥环插件

6.4.4.10 使用 HashiCorp Vault 密钥环插件

笔记

该keyring_hashicorp插件是商业产品 MySQL Enterprise Edition 中包含的扩展。要了解有关商业产品的更多信息，请参阅 https://www.mysql.com/products/。

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

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

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

示例（使用 SQL 接口）：

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

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

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

证书和密钥准备

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

company.crt：属于组织的自定义 CA 证书。keyring_hashicorpHashiCorp Vault 服务器和插件都使用此文件。
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 证书。
使用以下命令创建一个名为 name 的公司 CA 证书文件company.crt ，有效期为 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 服务器证书。
使用公司证书 ( ) 对来自 HashiCorp Vault 服务器密钥 ( vault.key) 和 CSR ( ) 的组合信息进行签名，以创建 HashiCorp Vault 服务器证书 ( )。使用以下命令执行此操作（在一行中输入命令）： request.csrcompany.crtvault.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 保险库设置

以下说明描述了如何创建有助于测试 keyring_hashicorp插件的 HashiCorp Vault 设置。

重要的

测试设置类似于生产设置，但 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 服务器私钥的密码 vault.key。
服务器应启动，并在控制台上显示一些信息（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 初始化期间获得的密钥。
保管库应产生指示设置已完成且保管库已开封的输出。
登录到 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 进行身份验证。认证成功需要提供两个secret给Vault，一个role ID和一个secret ID，这两个secret在概念上类似于user name和password。要使用的角色 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_pathkeyring_hashicorp_commit_role_idkeyring_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插件特定的系统变量和函数的其他信息，请参阅第 6.4.4.19 节，“密钥环系统变量”和第 6.4.4.16 节，“插件特定的密钥环密钥管理函数”。