6.4.4.4 使用 keyring_okv KMIP 插件

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

6.4.4.4 使用 keyring_okv KMIP 插件

笔记

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

密钥管理互操作性协议 (KMIP) 支持密钥管理服务器与其客户端之间的加密密钥通信。密钥环插件使用keyring_okv KMIP 1.1 协议作为 KMIP 后端的客户端进行安全通信。密钥环材料由后端专门生成，而不是由 keyring_okv. 该插件适用于这些 KMIP 兼容产品：

甲骨文密钥库
金雅拓 SafeNet KeySecure 设备
Townsend Alliance 主要经理

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

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

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

示例（使用 SQL 接口）：

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

有关第 6.4.4.6 节“支持的密钥环密钥类型和长度”keyring_okv允许的密钥值特征的信息。

要安装keyring_okv，请使用第 6.4.4.1 节“Keyring 插件安装”中的一般说明，以及此处提供的特定配置信息 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.orakeyring_okv：一个文件，其中包含与之通信的 KMIP 后端的详细信息。
ssl：包含与 KMIP 后端建立安全连接所需的证书和密钥文件的目录： CA.pem、、 cert.pem和 key.pem。从 MySQL 5.7.20 开始，如果密钥文件受密码保护，则该 ssl目录可以包含一个名为的单行文本文件 password.txt，其中包含解密密钥文件所需的密码。

需要具有证书和密钥文件的okvclient.ora文件和目录才能正常工作。用于使用这些文件填充配置目录的过程取决于与一起使用的 KMIP 后端，如其他地方所述。 sslkeyring_okvkeyring_okv

用作其支持文件位置的配置目录 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，请参阅第 6.4.4.12 节，“密钥环系统变量”。

为 Oracle Key Vault 配置 keyring_okv

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

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

以下过程简要总结了keyring_okv使用 Oracle Key Vault 进行设置的过程：

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

使用以下过程配置 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 管理控制台。
选择 Endpoints 选项卡以到达 Endpoints 页面。在端点页面上，单击添加。
提供所需的端点信息并单击注册。终结点类型应为其他。成功注册会产生一个注册令牌。
从 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文件，该文件应该位于 -d前面的java -jar命令中的选项命名的目录下的这个位置：
```
install_dir/conf/okvclient.ora
```
文件内容包括如下所示的行：
```
SERVER=host_ip:port_num
STANDBY_SERVER=host_ip:port_num
```
该keyring_okv插件尝试与在SERVER变量命名的主机上运行的服务器通信，STANDBY_SERVER如果失败则返回：
- 对于SERVER变量，okvclient.ora文件中的设置是强制性的。
- 对于STANDBY_SERVER变量，okvclient.ora文件中的设置是可选的，从 MySQL 5.7.19 开始。在 MySQL 5.7.19 之前，对于的设置 STANDBY_SERVER是强制性的；如果 okvclient.ora在没有设置的情况下生成STANDBY_SERVER，则keyring_okv无法初始化。解决方法是检查 oraclient.ora并添加一个 “虚拟”设置 STANDBY_SERVER（如果缺少）。例如：
```
STANDBY_SERVER=127.0.0.1:5696
```
转到 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
```
使用此命令从文件中提取ssl 包含 SSL 材料的 okvclient.jar目录：
```
jar xf okvclient.jar ssl
```
将 Oracle Key Vault 支持文件（ okvclient.ora文件和 ssl目录）复制到配置目录中。
（可选）如果您希望使用密码保护密钥文件，请使用密码保护 keyring_okv 密钥文件中的说明。

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

为金雅拓 SafeNet KeySecure 设备配置 keyring_okv

Gemalto SafeNet KeySecure Appliance 使用 KMIP 协议（版本 1.1 或 1.2）。从 MySQL 5.7.18 开始，密钥环keyring_okv插件（支持 KMIP 1.1）可以使用 KeySecure 作为密钥环存储的 KMIP 后端。

使用以下过程配置 keyring_okv和 KeySecure 一起工作。该描述仅总结了如何与 KeySecure 交互。有关详细信息，请参阅KeySecure 用户指南中名为添加 KMIP 服务器的部分。

创建包含 KeySecure 支持文件的配置目录，并确保将 keyring_okv_conf_dir 系统变量设置为命名该目录（有关详细信息，请参阅常规 keyring_okv 配置）。
在配置目录中，创建一个名为 name 的子目录ssl，用于存储所需的 SSL 证书和密钥文件。
在配置目录中，创建一个名为 okvclient.ora. 它应该具有以下格式：
```
SERVER=host_ip:port_num
STANDBY_SERVER=host_ip:port_num
```
例如，如果 KeySecure 在主机 198.51.100.20 上运行并侦听端口 9002，则该 okvclient.ora文件如下所示：
```
SERVER=198.51.100.20:9002
STANDBY_SERVER=198.51.100.20:9002
```
以具有证书颁发机构访问凭据的管理员身份连接到 KeySecure 管理控制台。
导航到安全 >> 本地 CA 并创建本地证书颁发机构 (CA)。
转到受信任的 CA 列表。选择默认并单击属性。然后为受信任的证书颁发机构列表选择编辑并添加刚刚创建的 CA。
下载 CA 并将其 ssl作为名为 CA.pem.
导航到安全 >> 证书请求并创建证书。然后您可以下载包含证书 PEM 文件的压缩 tar文件。
从下载的文件中提取 PEM 文件。例如，如果文件名为 csr_w_pk_pkcs8.gz，请使用以下命令解压缩并解压缩它：
```
tar zxvf csr_w_pk_pkcs8.gz
```
Two files result from the extraction operation: certificate_request.pem and private_key_pkcs8.pem.
Use this openssl command to decrypt the private key and create a file named key.pem:
```
openssl pkcs8 -in private_key_pkcs8.pem -out key.pem
```
Copy the key.pem file into the ssl directory.
Copy the certificate request in certificate_request.pem into the clipboard.
Navigate to Security >> Local CAs. Select the same CA that you created earlier (the one you downloaded to create the CA.pem file), and click Sign Request. Paste the Certificate Request from the clipboard, choose a certificate purpose of Client (the keyring is a client of KeySecure), and click Sign Request. The result is a certificate signed with the selected CA in a new page.
Copy the signed certificate to the clipboard, then save the clipboard contents as a file named cert.pem in the ssl directory.
(Optional) If you wish to password-protect the key file, use the instructions in Password-Protecting the keyring_okv Key File.

After completing the preceding procedure, restart the MySQL server. It loads the keyring_okv plugin and keyring_okv uses the files in its configuration directory to communicate with KeySecure.

Configuring keyring_okv for Townsend Alliance Key Manager

Townsend Alliance Key Manager uses the KMIP protocol. The keyring_okv keyring plugin can use Alliance Key Manager as its KMIP back end for keyring storage. For additional information, see Alliance Key Manager for MySQL.

Password-Protecting the keyring_okv Key File

As of MySQL 5.7.20, you can optionally protect the key file with a password and supply a file containing the password to enable the key file to be decrypted. To so do, change location to the ssl directory and perform these steps:

Encrypt the key.pem key file. For example, use a command like this, and enter the encryption password at the prompts:
```
$> openssl rsa -des3 -in key.pem -out key.pem.new
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
```
Save the encryption password in a single-line text file named password.txt in the ssl directory.
使用以下命令验证是否可以解密加密的密钥文件。解密后的文件应该显示在控制台上：
```
$> openssl rsa -in key.pem.new -passin file:password.txt
```
删除原始key.pem文件并重命名key.pem.new为 key.pem.
根据需要更改新 key.pem文件和 password.txt文件的所有权和访问模式，以确保它们与ssl目录中的其他文件具有相同的限制。