#### 6.4.4.10 使用 HashiCorp Vault Keyring 插件

[](<>)[](<>)

笔记

这`keyring_hashicorp`plugin 是商业产品 MySQL 企业版中包含的扩展。要了解有关商业产品的更多信息，请参阅<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.14 节，“通用密钥环密钥管理功能”](keyring-functions-general-purpose.html).

-   C接口：在C语言代码中，调用描述的keyring服务函数[第 5.6.9.2 节，“密钥环服务”](keyring-service.html).

    示例（使用 SQL 接口）：


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

有关键值特征的信息`keyring_hashicorp`， 看[第 6.4.4.12 节，“支持的密钥环密钥类型和长度”](keyring-key-types.html).

安装`keyring_hashicorp`, 使用中的一般说明[第 6.4.4.3 节，“密钥环插件安装”](keyring-plugin-installation.html)，以及特定于的配置信息`keyring_hashicorp`在这里找到。插件特定的配置包括准备连接到 HashiCorp Vault 所需的证书和密钥文件，以及配置 HashiCorp Vault 本身。以下部分提供了必要的说明。

-   [证书和密钥准备](keyring-hashicorp-plugin.html#keyring-hashicorp-certificate-configuration)

-   [HashiCorp 保管库设置](keyring-hashicorp-plugin.html#keyring-hashicorp-vault-configuration)

-   [钥匙圈\_hashcorp 配置](keyring-hashicorp-plugin.html#keyring-hashicorp-plugin-configuration)

##### 证书和密钥准备

[](<>)

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

-   `公司.crt`：属于组织的自定义 CA 证书。HashiCorp Vault 服务器和`keyring_hashicorp`插入。

-   `保险库密钥`: HashiCorp Vault 服务器实例的私钥。该文件由 HashiCorp Vault 服务器使用。

-   `保险库.crt`: HashiCorp Vault 服务器实例的证书。此文件必须由组织 CA 证书签名。

    以下说明描述了如何使用 OpenSSL 创建证书和密钥文件。（如果您已经拥有这些文件，请继续[HashiCorp 保管库设置](keyring-hashicorp-plugin.html#keyring-hashicorp-vault-configuration).) 所示说明适用于 Linux 平台，可能需要针对其他平台进行调整。

重要的

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

1.  准备公司和 HashiCorp Vault 服务器密钥。

    使用以下命令生成密钥文件：

    ```
    openssl genrsa -aes256 -out company.key 4096
    openssl genrsa -aes256 -out vault.key 2048
    ```

    这些命令生成保存公司私钥的文件（`公司密钥`) 和 Vault 服务器私钥 (`保险库密钥`）。密钥分别是随机生成的 4,096 位和 2,048 位的 RSA 密钥。

    每个命令都会提示输入密码。出于测试目的，不需要密码。要禁用它，请省略`-aes256`争论。

    密钥文件包含敏感信息，应存储在安全位置。稍后需要密码（也是敏感密码），因此请记下并将其存储在安全位置。

    （可选）要检查密钥文件的内容和有效性，请使用以下命令：

    ```
    openssl rsa -in company.key -check
    openssl rsa -in vault.key -check
    ```

2.  创建公司 CA 证书。

    使用以下命令创建一个名为的公司 CA 证书文件`公司.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 []:
    ```

    用适当的值回答提示。

3.  创建证书签名请求。

    要创建 HashiCorp Vault 服务器证书，必须为新创建的服务器密钥准备证书签名请求 (CSR)。创建一个名为`请求.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
    ```

    输出文件（`请求.csr`) 是一个中间文件，用作创建服务器证书的输入。

4.  创建 HashiCorp Vault 服务器证书。

    从 HashiCorp Vault 服务器密钥 (`保险库密钥`) 和企业社会责任 (`请求.csr`) 连同公司证书 (`公司.crt`) 创建 HashiCorp Vault 服务器证书 (`保险库.crt`）。使用以下命令执行此操作（在一行中输入命令）：

    ```
    openssl x509 -req -in request.csr
      -CA company.crt -CAkey company.key -CAcreateserial
      -out vault.crt -days 365 -sha256
    ```

    为了使`保险库.crt`服务器证书有用，追加内容`公司.crt`公司证书给它。这是必需的，以便公司证书与请求中的服务器证书一起交付。

    ```
    cat company.crt >> vault.crt
    ```

    如果显示的内容`保险库.crt`文件，它应该如下所示：

    ```
    -----BEGIN CERTIFICATE-----
    ... content of HashiCorp Vault server certificate ...
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    ... content of company certificate ...
    -----END CERTIFICATE-----
    ```

##### HashiCorp 保管库设置

[](<>)

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

重要的

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

这些说明假定在 中创建的证书和密钥文件可用[证书和密钥准备](keyring-hashicorp-plugin.html#keyring-hashicorp-certificate-configuration).如果您没有这些文件，请参阅该部分。

1.  获取 HashiCorp Vault 二进制文件。

    从以下位置下载适合您平台的 HashiCorp Vault 二进制文件<https://www.vaultproject.io/downloads.html>.

    提取存档的内容以生成可执行文件**金库**命令，用于执行 HashiCorp Vault 操作。如有必要，将安装命令的目录添加到系统路径。

    （可选）HashiCorp Vault 支持自动完成选项，使其更易于使用。有关详细信息，请参阅<https://learn.hashicorp.com/vault/getting-started/install#command-completion>.

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

    准备一个名为`配置。盐酸`包含以下内容。对于`tls_证书_文件`,`tls_密钥_文件`和`路径`值，替换适合您的系统的路径名。

    ```
    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
    ```

3.  启动HashiCorp Vault服务器。

    要启动Vault服务器，请使用以下命令，其中`-配置`选项指定刚创建的配置文件的路径：

    ```
    vault server -config=config.hcl
    ```

    在此步骤中，系统可能会提示您输入存储在中的Vault服务器私钥的密码`金库钥匙`文件

    服务器应该启动，在控制台上显示一些信息（IP、端口等）。

    为了输入剩余的命令，请将**保险库服务器**继续之前，请在后台执行命令或打开另一个终端。

4.  初始化HashiCorp Vault服务器。

    笔记

    只有在第一次启动Vault时，才需要执行此步骤中描述的操作，以获取解锁密钥和根令牌。后续Vault实例重新启动只需要使用unchal键进行解封。

    发出以下命令（假设Bourne shell语法）：

    ```
    export VAULT_SKIP_VERIFY=1
    vault operator init -n 1 -t 1
    ```

    第一个命令启用**金库**命令暂时忽略尚未将公司证书添加到系统信任存储的事实。它补偿了我们的自签名CA未添加到该存储的事实。（对于生产使用，应添加此类证书。）

    第二个命令创建一个单独的解封密钥，要求有一个单独的解封密钥用于解封。（对于生产使用，一个实例将有多个未密封密钥，需要输入的密钥最多为打开该实例所需的密钥数。未密封密钥应交付给公司内的密钥保管人。使用单个密钥可能会被视为安全问题，因为这允许由单个密钥保管人打开保险库。）

    Vault应回复有关解封密钥和根令牌的信息，以及一些附加文本（实际的解封密钥和根令牌值与此处显示的值不同）：

    ```
    ...
    Unseal Key 1: I2xwcFQc892O0Nt2pBiRNlnkHzTUrWS+JybL39BjcOE=
    Initial Root Token: s.vTvXeo3tPEYehfcd9WH7oUKz
    ...
    ```

    将解封密钥和根令牌存储在安全位置。

5.  解封HashiCorp Vault服务器。

    使用以下命令解封Vault服务器：

    ```
    vault operator unseal
    ```

    当提示输入解锁密钥时，请使用之前在Vault初始化期间获得的密钥。

    Vault应生成输出，指示设置已完成且Vault已打开。

6.  登录HashiCorp Vault服务器并验证其状态。

    准备以root用户身份登录所需的环境变量：

    ```
    vault login s.vTvXeo3tPEYehfcd9WH7oUKz
    ```

    对于该命令中的标记值，替换之前在Vault初始化期间获得的根标记的内容。

    验证Vault服务器状态：

    ```
    vault status
    ```

    输出应包含以下行（以及其他行）：

    ```
    ...
    Initialized     true
    Sealed          false
    ...
    ```

7.  设置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
    ```

8.  添加适当的安全策略。

    笔记

    只有在第一次运行Vault实例时，才需要执行此步骤中描述的操作。之后无需重复。

    准备一个允许之前创建的角色访问适当机密的策略。创建一个名为`mysql。盐酸`包括以下内容：

    ```
    path "kv/mysql/*" {
      capabilities = ["create", "read", "update", "delete", "list"]
    }
    ```

    笔记

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

    将策略文件导入Vault服务器以创建名为`mysql策略`，然后将策略分配给新角色：

    ```
    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
    ```

    生成这些可批准的角色ID和机密ID凭据后，它们将无限期地保持有效。它们不需要再次生成，并且`keyring_hashicorp`插件可以配置为持续使用。有关AuthRole身份验证的更多信息，请访问<https://www.vaultproject.io/docs/auth/approle.html>.

##### 钥匙圈\_hashicorp配置

[](<>)

插件库文件包含`keyring_hashicorp`插件和可加载函数，[`keyring_hashicorp_update_config（）`](keyring-functions-plugin-specific.html#function_keyring-hashicorp-update-config).当插件初始化和终止时，它会自动加载和卸载函数。无需手动加载和卸载该功能。

这个`keyring_hashicorp`插件支持下表所示的配置参数。要指定这些参数，请为相应的系统变量赋值。

| 配置参数 | 系统变量 | 强制性的 |
| ---- | ---- | ---- |
| HashiCorp服务器URL | [`密钥环\u hashicorp\u服务器\u url`](keyring-system-variables.html#sysvar_keyring_hashicorp_server_url) | 不 |
| 批准角色ID | [`keyring_hashicorp_role_id`](keyring-system-variables.html#sysvar_keyring_hashicorp_role_id) | 对 |
| 可批准的秘密身份证 | [`密钥环\u hashicorp\u secret\u id`](keyring-system-variables.html#sysvar_keyring_hashicorp_secret_id) | 对 |
| 存储路径 | [`密钥环\u hashicorp\u存储\u路径`](keyring-system-variables.html#sysvar_keyring_hashicorp_store_path) | 对 |
| 授权路径 | [`密钥环\u hashicorp\u auth\u路径`](keyring-system-variables.html#sysvar_keyring_hashicorp_auth_path) | 不 |
| CA证书文件路径 | [`密钥环\u hashicorp\u ca\u路径`](keyring-system-variables.html#sysvar_keyring_hashicorp_ca_path) | 不 |
| 缓存控制 | [`密钥环\u hashicorp\u缓存`](keyring-system-variables.html#sysvar_keyring_hashicorp_caching) | 不 |

要在服务器启动过程中可用，`keyring_hashicorp`必须使用[`--早期插件加载`](server-options.html#option_mysqld_early-plugin-load)选项如前表所示，几个与插件相关的系统变量是必需的，也必须设置。例如，在服务器中使用这些行`我的cnf`文件，调整`所以`根据需要为您的平台添加后缀和文件位置：

```
[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文档](https://www.vaultproject.io/api-docs)，所有API路由都以协议版本作为前缀（您可以在前面的示例中看到`/v1/`在[`密钥环\u hashicorp\u存储\u路径`](keyring-system-variables.html#sysvar_keyring_hashicorp_store_path)和[`密钥环\u hashicorp\u auth\u路径`](keyring-system-variables.html#sysvar_keyring_hashicorp_auth_path)价值观）。如果HashiCorp开发了新的协议版本，可能需要进行更改`/v1/`到配置中的其他内容。

MySQL服务器使用AppRole身份验证对HashiCorp Vault进行身份验证。成功的身份验证要求向Vault提供两个机密，一个角色ID和一个机密ID，这两个ID在概念上与用户名和密码类似。要使用的角色ID和机密ID值是在之前执行的HashiCorp Vault设置过程中获得的值。要指定这两个ID，请将其各自的值指定给[`keyring_hashicorp_role_id`](keyring-system-variables.html#sysvar_keyring_hashicorp_role_id)和[`密钥环\u hashicorp\u secret\u id`](keyring-system-variables.html#sysvar_keyring_hashicorp_secret_id)系统变量。设置过程还会导致存储路径为`/v1/kv/mysql`，这是要指定给的值[`keyring\u hashicorp\u commit\u store\u path`](keyring-system-variables.html#sysvar_keyring_hashicorp_commit_store_path).

在插件初始化时，`keyring_hashicorp`尝试使用配置值连接到HashiCorp Vault服务器。如果连接成功，插件会将这些值存储在相应的系统变量中`_承诺_`以他们的名义。例如，成功连接后，插件会存储[`keyring_hashicorp_role_id`](keyring-system-variables.html#sysvar_keyring_hashicorp_role_id)和[`密钥环\u hashicorp\u存储\u路径`](keyring-system-variables.html#sysvar_keyring_hashicorp_store_path)在里面[`keyring\u hashicorp\u commit\u role\u id`](keyring-system-variables.html#sysvar_keyring_hashicorp_commit_role_id)和[`keyring\u hashicorp\u commit\u store\u path`](keyring-system-variables.html#sysvar_keyring_hashicorp_commit_store_path).

运行时的重新配置可以在[`keyring_hashicorp_update_config（）`](keyring-functions-plugin-specific.html#function_keyring-hashicorp-update-config)功能：

1.  使用[`设置`](set-variable.html)语句将所需的新值分配给上表中所示的配置系统变量。这些任务本身对正在进行的插件操作没有影响。

2.  援引[`keyring_hashicorp_update_config（）`](keyring-functions-plugin-specific.html#function_keyring-hashicorp-update-config)使用新变量值使插件重新配置并重新连接到HashiCorp Vault服务器。

3.  如果连接成功，插件将更新的配置值存储在相应的系统变量中，这些系统变量`_承诺_`以他们的名义。

    例如，如果已将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，并且没有现有连接，则`_承诺_`系统变量设置为`“未承诺”`对于字符串值变量，以及`关`对于布尔值变量。如果插件无法连接，但存在现有连接，则该连接将保持活动状态，并且`_承诺_`变量反映用于它的值。

笔记

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

有关`keyring_hashicorp`插件特定的系统变量和函数，请参阅[第6.4.4.18节，“钥匙圈系统变量”](keyring-system-variables.html)和[第6.4.4.15节，“特定于插件的密钥环密钥管理功能”](keyring-functions-plugin-specific.html).
