MySQL :: MySQL 8.4 Reference Manual :: 8.4.4.6 Using the keyring

version 8.4

8.0 current
5.7

8.0 Japanese

MySQL 8.4 Reference Manual / ... / Using the keyring_okv KMIP Plugin

8.4.4.6 使用 OKV KMIP 插件

Note

OKV插件keyring_okv是MySQL Enterprise Edition的一部分，一个商业产品。要了解更多关于商业产品，请访问https://www.mysql.com/products/。

Key Management Interoperability Protocol（KMIP）使得加密密钥在key管理服务器和客户端之间进行通信。OKV插件keyring_okv使用KMIP 1.1协议作为KMIP后端的客户端，安全地与后端通信。密钥材料由后端生成，而不是keyring_okv。插件支持以下KMIP兼容产品：

Oracle Key Vault
Gemalto SafeNet KeySecure Appliance
Townsend Alliance Key Manager
Entrust KeyControl

每个MySQL Server实例都需要单独注册为KMIP客户端。如果两个或多个MySQL Server实例使用相同的凭证，他们可能会相互干扰。

OKV插件支持标准MySQL Keyring服务接口中的函数。Keyring操作由这些函数执行，可以在两个级别上访问：

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

示例（使用 SQL 接口）：

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

关于 keyring_okv 允许的关键值特征信息，请参阅第8.4.4.10节，“支持的密钥库密钥类型和长度”。

要安装 keyring_okv，请使用第8.4.4.3节，“密钥库插件安装”中的一般指令，并结合本文中特定于 keyring_okv 的配置信息。

无论使用哪种KMIP后端的keyring_okv插件存储密钥环，keyring_okv_conf_dir系统变量配置了keyring_okv用于支持文件的目录位置。默认值为空，因此您必须将变量设置为名称正确配置的目录，以便插件可以与KMIP后端通信。否则，keyring_okv在服务器启动时将写入错误日志，无法与KMIP后端通信：

[Warning] Plugin keyring_okv reported: 'For keyring_okv to be
initialized, please point the keyring_okv_conf_dir variable to a directory
containing Oracle Key Vault configuration file and ssl materials'

keyring_okv_conf_dir变量必须命名包含以下项目的目录：

okvclient.ora：KMIP后端与keyring_okv通信的详细信息文件。
ssl：包含用于建立安全连接的证书和密钥文件的目录：CA.pem，cert.pem和key.pem。如果密钥文件是密码保护的，可以在ssl目录中包含名为password.txt的单行文本文件，包含解密密钥文件所需的密码。

同时需要okvclient.ora文件和ssl目录中的证书和密钥文件，以便keyring_okv正常工作。用于将配置目录填充这些文件的过程取决于与keyring_okv使用的KMIP后端，详见其他地方。

keyring_okv 的支持文件所在目录的配置目录应该具有受限模式，并且只能由运行 MySQL 服务器的账户访问。例如，在 Unix 和 Unix 类系统上，使用/usr/local/mysql/mysql-keyring-okv 目录，可以执行以下命令（以 root 身份）创建目录并设置其模式和所有权：

cd /usr/local/mysql
mkdir mysql-keyring-okv
chmod 750 mysql-keyring-okv
chown mysql mysql-keyring-okv
chgrp mysql mysql-keyring-okv

在服务器启动过程中要使 keyring_okv 可用，需要使用--early-plugin-load 选项。同时，设置keyring_okv_conf_dir 系统变量，以便 keyring_okv 找到其配置目录。例如，在服务器my.cnf 文件中添加以下行，根据平台需要调整.so后缀和目录位置：

[mysqld]
early-plugin-load=keyring_okv.so
keyring_okv_conf_dir=/usr/local/mysql/mysql-keyring-okv

关于keyring_okv_conf_dir 的更多信息，请参见第8.4.4.16节，“Keyring System Variables”。

本讨论假设您熟悉 Oracle Key Vault。相关信息来源：

在 Oracle Key Vault 术语中，使用 Oracle Key Vault 存储和检索安全对象的客户端称为终点。为了与 Oracle Key Vault 通信，需要注册为终点并通过下载和安装终点支持文件进行 enroll。请注意，您必须为每个 MySQL 服务器实例注册一个单独的终点。如果两个或多个 MySQL 服务器实例使用同一个终点，他们可能会相互干扰。

以下过程简要概述了使用 Oracle Key Vault 配置 keyring_okv 的步骤：

创建 keyring_okv 插件使用的配置目录。
注册 Oracle Key Vault 终点以获取 enrollment 令牌。
使用 enrollment 令牌下载 okvclient.jar 客户端软件包。
安装客户端软件，以便将 Oracle Key Vault 支持文件填充到 keyring_okv 配置目录中。

使用以下步骤配置 keyring_okv 和 Oracle Key Vault 以实现协同工作。该描述仅简要概述如何与 Oracle Key Vault 交互。对于详细信息，请访问Oracle Key Vault网站，并查看 Oracle Key Vault 管理员指南。

创建包含Oracle Key Vault支持文件的配置目录，并确保设置了keyring_okv_conf_dir系统变量，以指向该目录（详见General keyring_okv Configuration）。
使用拥有系统管理员角色的用户登录Oracle Key Vault管理控制台。
选择“Endpoints”选项卡以访问“Endpoints”页面。在“Endpoints”页面中，单击“Add”。
提供所需的终点信息并单击“Register”。终点类型应为“Other”。注册成功将生成一个报名令牌。
从Oracle Key Vault服务器退出。
再次连接到Oracle Key Vault服务器，但这次不需要登录。使用报名令牌来报名并请求okvclient.jar软件下载。将该文件保存到您的系统中。
使用以下命令安装okvclient.jar文件（您必须具有JDK 1.4或更高版本）：
```
java -jar okvclient.jar -d dir_name [-v]
```
在-d选项后面的目录名称是要安装解压文件的位置。如果给出了-v选项，命令将产生可能有助于解决问题的日志信息。

当命令询问Oracle Key Vault终点密码时，不提供密码，而是按下Enter。（结果是终点连接到Oracle Key Vault时不需要密码。）

前面的命令将生成一个okvclient.ora文件，该文件应在由前面java -jar命令指定的目录下：
```
install_dir/conf/okvclient.ora
```
预期文件内容包括类似于以下这些行：
```
SERVER=host_ip:port_num
STANDBY_SERVER=host_ip:port_num
```
变量SERVER是必需的，变量STANDBY_SERVER是可选的。插件keyring_okv尝试与由变量SERVER指定的主机上的服务器通信，如果失败则 fallback 到STANDBY_SERVER。

Note

如果现有文件不在这个格式中，则创建一个新的文件，使用前面示例中的行。同时，考虑在运行okvutil命令之前备份okvclient.ora文件，并根据需要恢复该文件。

您可以指定多个备用服务器（最多64个）。如果您这样做，插件keyring_okv将迭代这些服务器直到建立连接，如果无法建立连接则失败。要添加额外的备用服务器，请编辑okvclient.ora文件，以指定服务器的IP地址和端口号作为STANDBY_SERVER变量的值。例如：
```
STANDBY_SERVER=host_ip:port_num,host_ip:port_num,host_ip:port_num,host_ip:port_num
```
确保备用服务器列表保持短、准确和最新，并删除无效的服务器。每次连接尝试都有20秒的等待时间，因此长列表中的无效服务器可以对插件keyring_okv的连接时间和服务器启动时间产生显著影响。
转到Oracle Key Vault安装目录，并使用以下命令测试设置：
```
okvutil/bin/okvutil list
```
输出结果应类似于以下内容：
```
Unique ID                               Type            Identifier
255AB8DE-C97F-482C-E053-0100007F28B9	Symmetric Key	-
264BF6E0-A20E-7C42-E053-0100007FB29C	Symmetric Key	-
```
对于一个没有任何密钥的Oracle Key Vault服务器（即无密钥的服务器），输出结果将如下所示，以指示vault中没有密钥：
```
no objects found
```
使用以下命令从okvclient.jar文件中提取ssl目录，包含SSL材料：
```
jar xf okvclient.jar ssl
```
将Oracle Key Vault支持文件（包括okvclient.ora文件和ssl目录）复制到配置目录中。
(可选)如果您想保护密钥文件，请按照密码保护keyring_okv密钥文件中的说明进行操作。

完成上述步骤后，重新启动MySQL服务器。它将加载keyring_okv插件，并使用配置目录中的文件与Oracle Key Vault通信。

Gemalto SafeNet KeySecure Appliance使用KMIP协议（版本1.1或1.2）。keyring_okv密钥环插件（支持KMIP 1.1）可以将KeySecure作为其KMIP后端用于密钥存储。

使用以下过程来配置keyring_okv和KeySecure以便它们能够协同工作。该描述仅总结如何与KeySecure交互。有关详细信息，请参阅KeySecure用户指南中的“添加KMIP服务器”部分。

创建包含KeySecure支持文件的配置目录，并确保keyring_okv_conf_dir系统变量设置为该目录名称（详见General keyring_okv Configuration）。
在配置目录中，创建名为ssl的子目录，以存储所需的SSL证书和密钥文件。
在配置目录中，创建一个名为okvclient.ora的文件。它应该具有以下格式：
```
SERVER=host_ip:port_num
STANDBY_SERVER=host_ip:port_num
```
例如，如果KeySecure在主机198.51.100.20上运行，并监听9002端口，同时也在备用主机203.0.113.125上运行，并监听8041端口，那么okvclient.ora文件将如下所示：
```
SERVER=198.51.100.20:9002
STANDBY_SERVER=203.0.113.125:8041
```
您可以指定多个备用服务器（最多64个）。如果您这样做，keyring_okv插件将遍历它们直到可以建立连接，然后失败。如果您想添加额外的备用服务器，请编辑okvclient.ora文件，以指定服务器IP地址和端口号为逗号分隔列表，STANDBY_SERVER变量的值。例如：
```
STANDBY_SERVER=host_ip:port_num,host_ip:port_num,host_ip:port_num,host_ip:port_num
```
确保备用服务器列表保持短、准确和最新，并删除无效的服务器。每次连接尝试都需要20秒的等待，因此长列表中的无效服务器可以对keyring_okv插件的连接时间和服务器启动时间产生显著影响。
以证书授权机构访问凭证连接到KeySecure管理控制台。
导航到安全>>本地CA，创建一个本地证书颁发机构（CA）。
转到受信任的CA列表。选择“Default”并单击“Properties”。然后，选择编辑受信任证书颁发机构列表，并添加刚创建的CA。
下载CA并将其保存在ssl目录中，以文件名CA.pem。
导航到安全>>证书请求，创建一个证书。然后，您可以下载包含证书PEM文件的压缩tar文件。
从下载的文件中提取PEM文件。例如，如果文件名为csr_w_pk_pkcs8.gz
```
tar zxvf csr_w_pk_pkcs8.gz
```
提取操作结果两个文件：certificate_request.pem和private_key_pkcs8.pem。
使用openssl命令解密私钥并创建名为key.pem的文件：
```
openssl pkcs8 -in private_key_pkcs8.pem -out key.pem
```
将key.pem文件复制到ssl目录中。
将certificate_request.pem中的证书请求复制到剪贴板中。
转到“安全”->>“本地CA”。选择您之前创建的同一个CA（下载并用于创建CA.pem文件），然后单击“签名请求”。将证书请求从剪贴板中粘贴，选择客户端证书目的（keyring是KeySecure的客户端），然后单击“签名请求”。结果是一个使用所选CA签名的新页面。
将已签名的证书复制到剪贴板，然后将剪贴板内容保存为名为cert.pem的文件，在ssl目录下。
(可选)如果您想保护密钥文件，请按照密码保护keyring_okv密钥文件中的指令进行操作。

完成上述过程后，重新启动MySQL服务器。它将加载keyring_okv插件，并使用其配置目录中的文件与KeySecure通信。

Townsend Alliance Key Manager使用KMIP协议。keyring_okv密钥ring插件可以将Alliance Key Manager作为其KMIP后端用于密钥存储。对于更多信息，请见Alliance Key Manager for MySQL。

Entrust KeyControl 使用 KMIP 协议。 keyring_okv 密钥环插件可以使用 Entrust KeyControl 作为其 KMIP 后端来存储密钥。对于更多信息，请参阅Oracle MySQL 和 Entrust KeyControl with nShield HSM Integration Guide。

您可以选择使用密码保护密钥文件，并提供包含密码的文件以启用密钥文件解密。要这样做，请将位置更改到ssl目录，然后执行以下步骤：

加密key.pem密钥文件。例如，可以使用以下命令，并在提示中输入加密密码：

$> openssl rsa -des3 -in key.pem -out key.pem.new
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

将加密密码保存到名为password.txt的单行文本文件中，在ssl目录下。
验证使用以下命令可以解密加密密钥文件。解密后的文件应在控制台上显示：
```
$> openssl rsa -in key.pem.new -passin file:password.txt
```
删除原始key.pem文件，并将key.pem.new重命名为key.pem。
根据需要更改新key.pem文件和password.txt文件的所有权和访问模式，以确保它们具有与其他ssl目录中的文件相同的限制。

PREV HOME UP NEXT