MySQL :: MySQL 8.4 参考手册 :: 8.4.4.6 使用 keyring_okv KMIP 插件

版本 8.4

8.0 日语

MySQL 8.4 参考手册 / ... / 使用 keyring_okv KMIP 插件

8.4.4.6 使用 keyring_okv KMIP 插件

注意

keyring_okv 插件是 MySQL 企业版（一种商业产品）中包含的扩展。要详细了解商业产品，请参阅 https://www.mysqlserver.cn/products/。

密钥管理互操作性协议 (KMIP) 支持密钥管理服务器与其客户端之间进行加密密钥的通信。keyring_okv 密钥环插件使用 KMIP 1.1 协议作为 KMIP 后端的客户端安全地进行通信。密钥环材料完全由后端生成，而不是由 keyring_okv 生成。该插件可与以下兼容 KMIP 的产品配合使用

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

每个 MySQL 服务器实例都必须单独注册为 KMIP 的客户端。如果两个或多个 MySQL 服务器实例使用同一组凭据，它们可能会相互干扰。

keyring_okv 插件支持构成标准 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_okv 允许的密钥值特征的信息，请参阅第 8.4.4.10 节“支持的密钥环密钥类型和长度”。

要安装 keyring_okv，请使用第 8.4.4.3 节“密钥环插件安装”中的一般说明，以及此处提供的特定于 keyring_okv 的配置信息。

通用 keyring_okv 配置

无论 keyring_okv 插件使用哪个 KMIP 后端进行密钥环存储，keyring_okv_conf_dir 系统变量都会配置 keyring_okv 用于其支持文件的目录位置。默认值为空，因此必须将该变量设置为命名一个配置正确的目录，然后该插件才能与 KMIP 后端通信。除非这样做，否则 keyring_okv 会在服务器启动期间向错误日志写入一条消息，指出它无法通信

[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：一个包含 keyring_okv 与之通信的 KMIP 后端详细信息的文件。
ssl：一个包含与 KMIP 后端建立安全连接所需的证书和密钥文件的目录：CA.pem、cert.pem 和 key.pem。如果密钥文件受密码保护，则 ssl 目录可以包含一个名为 password.txt 的单行文本文件，其中包含解密密钥文件所需的密码。

要使 keyring_okv 正常工作，需要 okvclient.ora 文件和包含证书和密钥文件的 ssl 目录。用于使用这些文件填充配置目录的过程取决于与 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

为了在服务器启动过程中可用，必须使用 --early-plugin-load 选项加载 keyring_okv。此外，请设置 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 系统变量”。

为 Oracle Key Vault 配置 keyring_okv

此处的讨论假定您熟悉 Oracle Key Vault。一些相关的信息来源

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

以下过程简要概述了设置 keyring_okv 以与 Oracle Key Vault 一起使用的过程

创建 keyring_okv 插件要使用的配置目录。
在 Oracle Key Vault 中注册一个端点以获取注册令牌。
使用注册令牌获取 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 系统变量设置为该目录的名称（有关详细信息，请参阅常规 keyring_okv 配置）。
以具有系统管理员角色的用户身份登录 Oracle Key Vault 管理控制台。
选择“端点”选项卡以进入“端点”页面。在“端点”页面上，单击“添加”。
提供所需的端点信息，然后单击“注册”。端点类型应为“其他”。成功注册将生成注册令牌。
从 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 命令中 -d 选项命名的目录下的此位置
```
install_dir/conf/okvclient.ora
```
预期的文件内容包括如下所示的行
```
SERVER=host_ip:port_num
STANDBY_SERVER=host_ip:port_num
```
SERVER 变量是必需的，而 STANDBY_SERVER 变量是可选的。 keyring_okv 插件尝试与在 SERVER 变量命名的主机上运行的服务器通信，如果失败，则回退到 STANDBY_SERVER。

注意

如果现有文件不是此格式，请使用上例中显示的行创建一个新文件。另外，请考虑在运行 okvutil 命令之前备份 okvclient.ora 文件。根据需要还原文件。

您可以指定多个备用服务器（最多 64 个）。如果这样做，则 keyring_okv 插件将对其进行迭代，直到可以建立连接为止，如果无法建立连接，则将失败。要添加额外的备用服务器，请编辑 okvclient.ora 文件以在 STANDBY_SERVER 变量的值中将服务器的 IP 地址和端口号指定为逗号分隔的列表。例如
```
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 服务器（其中没有任何密钥的服务器），输出如下所示，表示保险库中没有密钥
```
no objects found
```
使用以下命令从 okvclient.jar 文件中提取包含 SSL 材料的 ssl 目录
```
jar xf okvclient.jar ssl
```
将 Oracle Key Vault 支持文件（okvclient.ora 文件和 ssl 目录）复制到配置目录中。
（可选）如果要使用密码保护密钥文件，请使用使用密码保护 keyring_okv 密钥文件中的说明。

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

为 Gemalto SafeNet KeySecure Appliance 配置 keyring_okv

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 系统变量设置为该目录的名称（有关详细信息，请参阅常规 keyring_okv 配置）。
在配置目录中，创建一个名为 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 文件以在 STANDBY_SERVER 变量的值中将服务器的 IP 地址和端口号指定为逗号分隔的列表。例如
```
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 列表”。选择“默认”，然后单击“属性”。然后，为“受信任的证书颁发机构列表”选择“编辑”，并添加刚刚创建的 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 文件的 CA），然后单击“签名请求”。从剪贴板粘贴“证书请求”，选择“客户端”的证书用途（密钥环是 KeySecure 的客户端），然后单击“签名请求”。结果是在新页面中使用所选 CA 签名的证书。
将签名的证书复制到剪贴板，然后将剪贴板内容另存为一个名为 cert.pem 的文件，并将其保存在 ssl 目录中。
（可选）如果要使用密码保护密钥文件，请使用使用密码保护 keyring_okv 密钥文件中的说明。

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

为 Townsend Alliance Key Manager 配置 keyring_okv

Townsend Alliance Key Manager 使用 KMIP 协议。 keyring_okv 密钥环插件可以使用 Alliance Key Manager 作为其密钥环存储的 KMIP 后端。有关其他信息，请参见适用于 MySQL 的 Alliance Key Manager。

为 Entrust KeyControl 配置 keyring_okv

Entrust KeyControl 使用 KMIP 协议。 keyring_okv 密钥环插件可以使用 Entrust KeyControl 作为其密钥环存储的 KMIP 后端。有关其他信息，请参见《Oracle MySQL 和 Entrust KeyControl 与 nShield HSM 集成指南》。

使用密码保护 keyring_okv 密钥文件

您可以选择使用密码保护密钥文件，并提供包含该密码的文件以启用对密钥文件的解密。为此，请将位置更改为 ssl 目录并执行以下步骤

加密 key.pem 密钥文件。例如，使用如下所示的命令，并在提示符下输入加密密码

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

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