使用keyring_hashicorp插件

注意
该keyring_hashicorp插件是商业产品MySQL企业版中的扩展。要了解有关商业产品的更多信息，请参见 https://www.mysql.com/products/。

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

该keyring_hashicorp插件支持包含标准MySQL Keyring服务接口的功能。这些功能执行的密钥环操作可从两个级别访问：

SQL接口：在SQL语句中，调用“通用密钥环密钥管理功能”中所述的用户定义函数（UDF）。
C接口：在C语言代码中，调用“密钥环服务”中所述的密钥环服务功能。

示例（使用UDF）：

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

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

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

证书和密钥准备
HashiCorp保管库设置
keyring_hashicorp配置

证书和密钥准备

该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）的文件。这些密钥分别是随机生成的4,096和2,048位的RSA密钥。
每个命令都提示输入密码。（出于测试目的，不需要密码。要禁用密码，请省略-aes256参数。）
密钥文件包含敏感信息，应将其存储在安全的位置。稍后需要密码（也很敏感），因此请记下密码并将其存储在安全的位置。
（可选）要检查密钥文件的内容和有效性，请使用以下命令：
```
openssl rsa -in company.key -check
openssl rsa -in vault.key -check
```
创建公司CA证书。
使用以下命令来创建名为company.crt 365天有效的公司CA证书文件（在单行中输入命令）：
```
openssl req -x509 -new -nodes -key company.key
-sha256 -days 365 -out company.crt
```
如果在CA证书创建过程中使用该-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
uthorityKeyIdentifier = 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（request.csr）的组合信息，company.crt以创建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保管库设置

以下说明介绍了如何创建有助于测试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.key文件中存储的Vault服务器私钥的密码。
服务器应该启动，并在控制台上显示一些信息（IP，端口等）。
这样您就可以输入其余命令，将Vault服务器命令置于后台或打开另一个终端，然后再继续。
初始化HashiCorp Vault服务器。
注意
仅在首次启动Vault时才需要执行此步骤中描述的操作，以获取解封密钥和根令牌。随后的Vault实例重新启动仅需要使用解封密钥进行解封。
发出以下命令（假设使用Bourne shell语法）：
```
export VAULT_SKIP_VERIFY=1
vault operator init -n 1 -t 1
```
第一个命令使Vault命令可以暂时忽略没有公司证书已添加到系统信任库的事实。它弥补了我们的自签名CA未添加到该商店的事实。（对于生产用途，应添加此类证书。）
第二个命令创建单个解封密钥，要求存在一个解封密钥。（对于生产用途，一个实例将具有多个解封密钥，最多需要输入许多密钥才能解封该密钥。解封密钥应交付给公司内部的密钥保管人。单个密钥的使用可能被视为安全问题。因为这样可以使单个关键保管人将保管库打开。）
保管箱应回复有关解封密钥和根令牌的信息，外加一些其他文字（实际解封密钥和根令牌值将与此处显示的值不同）：
```
...
Unseal Key 1: I2xwcFQc892O0Nt2pBiRNlnkHzTUrWS	+JybL39BjcOE=
Initial Root Token: s.vTvXeo3tPEYehfcd9WH7oUKz
...
```
将解封密钥和根令牌存储在安全的位置。
解封HashiCorp Vault服务器。
使用以下命令解封Vault服务器：
```
vault operator unseal
```
当提示您输入解封密钥时，请使用在保管库初始化期间先前获得的密钥。
保管库应产生表明安装已完成且保管库未密封的输出。
登录到HashiCorp Vault服务器并验证其状态。
准备以root用户身份登录所需的环境变量：
```
vault login s.vTvXeo3tPEYehfcd9WH7oUKz
```
对于该命令中的令牌值，替换先前在保管库初始化期间获得的根令牌的内容。
验证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"]
}
```
将策略文件导入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插件和用户定义函数（UDF）keyring_hashicorp_update_config()。插件初始化和终止时，它会自动加载和卸载UDF，因此无需手动加载和卸载UDF。

该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'

MySQL Server使用AppRole身份验证针对HashiCorp Vault进行身份验证。成功的身份验证要求向保险柜提供两个机密，即角色ID和机密ID，它们在概念上与用户名和密码相似。要使用的角色ID和秘密ID值是先前在HashiCorp Vault设置过程中获得的角色ID和秘密ID值。要指定两个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 nd 的值存储keyring_hashicorp_store_path在keyring_hashicorp_commit_role_id和中keyring_hashicorp_commit_store_path。

可以在keyring_hashicorp_update_config() UDF 的帮助下在运行时重新配置：

使用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特定于插件的系统变量和UDF的更多信息，请参见“密钥环系统变量”和“特定于插件的密钥环密钥管理功能”。