#### 6.4.4.13 在密钥环密钥库之间迁移密钥

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

密钥环迁移将密钥从一个密钥库复制到另一个密钥库，使 DBA 能够将 MySQL 安装切换到不同的密钥库。成功的迁移操作具有以下结果：

-   目标密钥库包含它在迁移之前拥有的密钥，以及来自源密钥库的密钥。

-   迁移前后源密钥库保持不变（因为密钥是复制的，而不是移动的）。

    如果要复制的密钥已存在于目标密钥库中，则会发生错误，并且目标密钥库将恢复到其迁移前状态。

    密钥环使用密钥环组件和密钥环插件管理密钥库。这与迁移策略有关，因为管理源和目标密钥库的方式决定了特定类型的密钥迁移是否可行以及执行迁移的过程：

-   从一个密钥环插件迁移到另一个：MySQL 服务器具有提供此功能的操作模式。

-   从 keyring 插件迁移到 keyring 组件：从 MySQL 8.0.24 开始，MySQL 服务器具有提供此功能的操作模式。

-   从一个密钥环组件迁移到另一个：[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)实用程序提供此功能。[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)从 MySQL 8.0.24 开始可用。

-   从密钥环组件迁移到密钥环插件：没有提供此功能。

    以下部分讨论了离线和在线迁移的特征，并描述了如何执行迁移。

-   [离线和在线密钥迁移](keyring-key-migration.html#keyring-key-migration-offline-online)

-   [使用迁移服务器进行密钥迁移](keyring-key-migration.html#keyring-key-migration-using-migration-server)

-   [使用 mysql 进行密钥迁移\_迁移\_密钥环实用程序](keyring-key-migration.html#keyring-key-migration-using-mysql-migrate-keyring)

-   [涉及多个正在运行的服务器的密钥迁移](keyring-key-migration.html#keyring-key-migration-multiple-running-servers)

##### 离线和在线密钥迁移

密钥迁移是离线或在线的：

-   离线迁移：当您确定本地主机上没有正在运行的服务器正在使用源或目标密钥库时使用。在这种情况下，迁移操作可以将密钥从源密钥库复制到目标，而运行的服务器不可能在操作期间修改密钥库内容。

-   在线迁移：当本地主机上正在运行的服务器正在使用源密钥库时使用。在这种情况下，必须注意防止该服务器在迁移期间更新密钥库。这涉及连接到正在运行的服务器并指示它暂停密钥环操作，以便可以将密钥从源密钥库安全地复制到目标。密钥复制完成后，允许运行的服务器恢复密钥环操作。

    当您计划密钥迁移时，请使用以下几点来决定它应该是离线还是在线：

-   不要执行涉及正在运行的服务器使用的密钥库的脱机迁移。

-   在线迁移期间暂停密钥环操作是通过连接到正在运行的服务器并设置其全局[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)系统变量为`离开`在密钥复制之前和`在`密钥复制后。这有几个含义：

    -   [`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)在 MySQL 5.7.21 中引入，因此只有在运行的服务器来自 MySQL 5.7.21 或更高版本时才能进行在线迁移。如果正在运行的服务器较旧，您必须停止它，执行离线迁移，然后重新启动它。其他地方的所有迁移说明[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)受此条件约束。

    -   用于连接正在运行的服务器的帐户必须具有修改所需的权限[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations).这些特权是[`ENCRYPTION_KEY_ADMIN`](privileges-provided.html#priv_encryption-key-admin)除了[`SYSTEM_VARIABLES_ADMIN`](privileges-provided.html#priv_system-variables-admin)或已弃用的[`极好的`](privileges-provided.html#priv_super)特权。

    -   如果在线迁移操作异常退出（例如被强制终止），可能[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)在正在运行的服务器上保持禁用状态，使其无法执行密钥环操作。在这种情况下，可能需要连接到正在运行的服务器并启用[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)手动使用此语句：

        ```
        SET GLOBAL keyring_operations = ON;
        ```

-   在线密钥迁移提供在单个正在运行的服务器上暂停密钥环操作。如果多个正在运行的服务器正在使用所涉及的密钥库，要执行迁移，请使用在[涉及多个正在运行的服务器的密钥迁移](keyring-key-migration.html#keyring-key-migration-multiple-running-servers).

##### 使用迁移服务器进行密钥迁移

如果在支持密钥迁移的特殊操作模式下调用 MySQL 服务器，则会成为迁移服务器。迁移服务器不接受客户端连接。相反，它只运行足够长的时间来迁移密钥，然后退出。迁移服务器向控制台报告错误（标准错误输出）。

迁移服务器支持以下迁移类型：

-   从一个密钥环插件迁移到另一个。

-   从密钥环插件迁移到密钥环组件。此功能从 MySQL 8.0.24 开始可用。较旧的服务器仅支持从一个密钥环插件迁移到另一个，在这种情况下，这些说明中涉及密钥环组件的部分不适用。

    迁移服务器不支持从一个密钥环组件迁移到另一个。对于这种类型的迁移，请参阅[使用 mysql 进行密钥迁移\_迁移\_密钥环实用程序](keyring-key-migration.html#keyring-key-migration-using-mysql-migrate-keyring).

    要使用迁移服务器执行密钥迁移操作，请确定指定涉及哪些密钥环插件或组件以及迁移是离线还是在线所需的密钥迁移选项：

-   要指示源密钥环插件和目标密钥环插件或组件，请指定以下选项：

    -   [`--keyring-迁移源`](keyring-options.html#option_mysqld_keyring-migration-source)：管理要迁移的密钥的源密钥环插件。

    -   [`--keyring-migration-destination`](keyring-options.html#option_mysqld_keyring-migration-destination): 迁移的密钥要复制到的目标密钥环插件或组件。

    -   [`--keyring-migration-to-component`](keyring-options.html#option_mysqld_keyring-migration-to-component)：如果目标是密钥环组件而不是密钥环插件，则需要此选项。

        这[`--keyring-迁移源`](keyring-options.html#option_mysqld_keyring-migration-source)和[`--keyring-migration-destination`](keyring-options.html#option_mysqld_keyring-migration-destination)options 向服务器表明它应该在密钥迁移模式下运行。对于密钥迁移操作，这两个选项都是必需的。每个插件或组件都使用其库文件的名称指定，包括任何特定于平台的扩展名，例如`。所以`要么`.dll`.源和目标必须不同，并且迁移服务器必须同时支持它们。

-   对于离线迁移，不需要额外的密钥迁移选项。

-   对于在线迁移，一些正在运行的服务器当前正在使用源或目标密钥库。要调用迁移服务器，请指定指示如何连接到正在运行的服务器的其他关键迁移选项。这是必要的，以便迁移服务器可以连接到正在运行的服务器并告诉它在迁移操作期间暂停使用密钥环。

    使用以下任何选项都表示在线迁移：

    -   [`--keyring-迁移主机`](keyring-options.html#option_mysqld_keyring-migration-host): 运行服务器所在的主机。这始终是本地主机，因为迁移服务器只能在由本地插件和组件管理的密钥库之间迁移密钥。

    -   [`--keyring 迁移用户`](keyring-options.html#option_mysqld_keyring-migration-user),[`--keyring-migration-password`](keyring-options.html#option_mysqld_keyring-migration-password)：用于连接到正在运行的服务器的帐户凭据。

    -   [`--密钥环迁移端口`](keyring-options.html#option_mysqld_keyring-migration-port)：对于 TCP/IP 连接，要连接到正在运行的服务器上的端口号。

    -   [`--keyring-migration-socket`](keyring-options.html#option_mysqld_keyring-migration-socket)：对于 Unix 套接字文件或 Windows 命名管道连接，要连接到正在运行的服务器上的套接字文件或命名管道。

    有关密钥迁移选项的更多详细信息，请参阅[第 6.4.4.17 节，“密钥环命令选项”](keyring-options.html).

    使用指示源和目标密钥库以及迁移是离线还是在线的密钥迁移选项启动迁移服务器，可能还有其他选项。请记住以下注意事项：

-   可能需要其他服务器选项，例如两个密钥环插件的配置参数。例如，如果`密钥环文件`是源或目标，您必须设置[`密钥环文件数据`](keyring-system-variables.html#sysvar_keyring_file_data)如果密钥环数据文件位置不是默认位置，则为系统变量。可能还需要其他非密钥环选项。指定这些选项的一种方法是使用[`--defaults 文件`](option-file-options.html#option_general_defaults-file)命名包含所需选项的选项文件。

-   迁移服务器期望路径名选项值是完整路径。相对路径名可能无法如您预期的那样解析。

-   以密钥迁移模式调用服务器的用户不能是`根`操作系统用户，除非[`- 用户`](server-options.html#option_mysqld_user)选项用非指定`根`以该用户身份运行服务器的用户名。

-   以密钥迁移模式运行服务器的用户必须有权读取和写入任何本地密钥环文件，例如基于文件的插件的数据文件。

    如果您从不同于通常用于运行 MySQL 的系统帐户调用迁移服务器，它可能会创建在正常操作期间服务器无法访问的密钥环目录或文件。假设[**mysqld**](mysqld.html)通常作为`mysql`操作系统用户，但您在以身份登录时调用迁移服务器`伊莎贝尔`.迁移服务器创建的任何新目录或文件都归`伊莎贝尔`.当服务器作为`mysql`操作系统用户尝试访问拥有的文件系统对象`伊莎贝尔`.

    为避免此问题，请将迁移服务器作为`根`操作系统用户并提供一个[`--用户=*`用户名`*`](server-options.html#option_mysqld_user)选项，在哪里*`用户名`*是通常用于运行 MySQL 的系统帐户。或者，在迁移之后，检查与密钥环相关的文件系统对象，并在必要时使用**chown**,**修改**，或类似的命令，以便正在运行的服务器可以访问对象。

    用于在两个密钥环插件之间进行离线迁移的示例命令行（在一行中输入命令）：


```
mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-source=keyring_file.so
  --keyring-migration-destination=keyring_encrypted_file.so
  --keyring_encrypted_file_password=password
```

两个密钥环插件之间在线迁移的示例命令行：

```
mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-source=keyring_file.so
  --keyring-migration-destination=keyring_encrypted_file.so
  --keyring_encrypted_file_password=password
  --keyring-migration-host=127.0.0.1
  --keyring-migration-user=root
  --keyring-migration-password=root_password
```

要在目标是密钥环组件而不是密钥环插件时执行迁移，请指定[`--keyring-migration-to-component`](keyring-options.html#option_mysqld_keyring-migration-to-component)选项，并将组件命名为[`--keyring-migration-destination`](keyring-options.html#option_mysqld_keyring-migration-destination)选项。

从密钥环插件到密钥环组件的离线迁移示例命令行：

```
mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-to-component
  --keyring-migration-source=keyring_file.so
  --keyring-migration-destination=component_keyring_encrypted_file.so
```

请注意，在这种情况下，没有`keyring_encrypted_file_password`值被指定。组件数据文件的密码列在组件配置文件中。

从 keyring 插件到 keyring 组件的在线迁移示例命令行：

```
mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-to-component
  --keyring-migration-source=keyring_file.so
  --keyring-migration-destination=component_keyring_encrypted_file.so
  --keyring-migration-host=127.0.0.1
  --keyring-migration-user=root
  --keyring-migration-password=root_password
```

密钥迁移服务器执行迁移操作如下：

1.  （仅限在线迁移）使用连接选项连接到正在运行的服务器。

2.  （仅限在线迁移）禁用[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)在正在运行的服务器上。

3.  为源和目标密钥库加载密钥环插件/组件库。

4.  将源密钥库中的密钥复制到目标。

5.  卸载源和目标密钥库的密钥环插件/组件库。

6.  （仅限在线迁移）启用[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)在正在运行的服务器上。

7.  （仅限在线迁移）断开与正在运行的服务器的连接。

    如果在密钥迁移过程中发生错误，则目标密钥库将恢复到其迁移前状态。

    成功进行在线密钥迁移操作后，可能需要重新启动正在运行的服务器：

-   如果正在运行的服务器在迁移之前正在使用源密钥库，并且应该在迁移后继续使用它，则迁移后无需重新启动它。

-   如果正在运行的服务器在迁移之前正在使用目标密钥库，并且应该在迁移之后继续使用它，则应该在迁移后重新启动以加载所有迁移到目标密钥库中的密钥。

-   如果正在运行的服务器在迁移之前使用源密钥库，但在迁移之后应该使用目标密钥库，则必须将其重新配置为使用目标密钥库并重新启动。在这种情况下，请注意，虽然正在运行的服务器在迁移过程中暂停修改源密钥库，但在迁移和后续重启之间的时间间隔内不会暂停。应注意服务器在此间隔期间不要修改源密钥库，因为任何此类更改都不会反映在目标密钥库中。

##### 使用 mysql 进行密钥迁移\_迁移\_密钥环实用程序

这[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)实用程序将密钥从一个密钥环组件迁移到另一个。它不支持涉及密钥环插件的迁移。对于该类型的迁移，请使用以密钥迁移模式运行的 MySQL 服务器；看[使用迁移服务器进行密钥迁移](keyring-key-migration.html#keyring-key-migration-using-migration-server).

使用执行密钥迁移操作[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)，确定指定涉及哪些密钥环组件所需的密钥迁移选项，以及迁移是离线还是在线：

-   要指示源和目标密钥环组件及其位置，请指定以下选项：

    -   [`--source-keyring`](mysql-migrate-keyring.html#option_mysql_migrate_keyring_source-keyring)：管理要迁移的密钥的源密钥环组件。

    -   [`--destination-keyring`](mysql-migrate-keyring.html#option_mysql_migrate_keyring_destination-keyring): 迁移的密钥要复制到的目标密钥环组件。

    -   `--组件目录`：包含密钥环组件库文件的目录。这通常是[`插件目录`](server-system-variables.html#sysvar_plugin_dir)本地 MySQL 服务器的系统变量。

        这三个选项都是强制性的。每个密钥环组件名称都是指定的组件库文件名，没有任何特定于平台的扩展名，例如`。所以`要么`.dll`.例如，要使用库文件所在的组件`component_keyring_file.so`, 指定选项为[`--source-keyring=component_keyring_file`](mysql-migrate-keyring.html#option_mysql_migrate_keyring_source-keyring).来源和目的地必须不同，并且[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)必须支持他们两个。

-   对于离线迁移，不需要其他选项。

-   对于在线迁移，一些正在运行的服务器当前正在使用源或目标密钥库。在这种情况下，指定`--在线迁移`表示在线迁移的选项。此外，指定连接选项以指示如何连接到正在运行的服务器，以便[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)可以连接到它并告诉它在迁移操作期间暂停使用密钥环。

    这`--在线迁移`选项通常与连接选项结合使用，例如：

    -   [`- 主持人`](mysql-migrate-keyring.html#option_mysql_migrate_keyring_host): 运行服务器所在的主机。这始终是本地主机，因为[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)只能在本地组件管理的密钥库之间迁移密钥。

    -   [`- 用户`](mysql-migrate-keyring.html#option_mysql_migrate_keyring_user),[`- 密码`](mysql-migrate-keyring.html#option_mysql_migrate_keyring_password)：用于连接到正在运行的服务器的帐户凭据。

    -   [`- 港口`](mysql-migrate-keyring.html#option_mysql_migrate_keyring_port)：对于 TCP/IP 连接，要连接到正在运行的服务器上的端口号。

    -   [`- 插座`](mysql-migrate-keyring.html#option_mysql_migrate_keyring_socket)：对于 Unix 套接字文件或 Windows 命名管道连接，要连接到正在运行的服务器上的套接字文件或命名管道。

    有关所有可用选项的说明，请参阅[第 4.6.8 节，“mysql\_迁移\_keyring — Keyring 密钥迁移实用程序”](mysql-migrate-keyring.html).

    开始[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)带有指示源和目标密钥库以及迁移是脱机还是联机的选项，可能还有其他选项。请记住以下注意事项：

-   调用的用户[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)不能是`根`操作系统用户。

-   调用的用户[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)必须有权读取和写入任何本地密钥环文件，例如基于文件的插件的数据文件。

    如果你调用[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)从与通常用于运行 MySQL 的系统帐户不同的系统帐户，它可能会创建在正常操作期间服务器无法访问的密钥环目录或文件。假设[**mysqld**](mysqld.html)通常作为`mysql`操作系统用户，但您调用[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)登录为`伊莎贝尔`.由创建的任何新目录或文件[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)拥有`伊莎贝尔`.当服务器作为`mysql`操作系统用户尝试访问拥有的文件系统对象`伊莎贝尔`.

    为避免此问题，请调用[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)作为`mysql`操作系统用户。或者，在迁移之后，检查与密钥环相关的文件系统对象，并在必要时使用**chown**,**修改**，或类似的命令，以便正在运行的服务器可以访问对象。

    假设您要从`组件密钥环文件`到`组件密钥环加密文件`，并且本地服务器将其密钥环组件库文件存储在`/usr/local/mysql/lib/plugin`.

    如果没有正在运行的服务器正在使用密钥环，则允许离线迁移。调用[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)像这样（在一行中输入命令）：


```
mysql_migrate_keyring
  --component-dir=/usr/local/mysql/lib/plugin
  --source-keyring=component_keyring_file
  --destination-keyring=component_keyring_encrypted_file
```

如果正在运行的服务器正在使用密钥环，则必须改为执行在线迁移。在这种情况下，`--在线迁移`必须给出选项，以及指定要连接到哪个服务器和要使用的 MySQL 帐户所需的任何连接选项。

以下命令执行在线迁移。它使用 TCP/IP 连接和本地服务器连接`行政`帐户。该命令提示输入密码，您应在出现提示时输入密码：

```
mysql_migrate_keyring
  --component-dir=/usr/local/mysql/lib/plugin
  --source-keyring=component_keyring_file
  --destination-keyring=component_keyring_encrypted_file
  --online-migration --host=127.0.0.1 --user=admin --password
```

[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)执行如下迁移操作：

1.  （仅限在线迁移）使用连接选项连接到正在运行的服务器。

2.  （仅限在线迁移）禁用[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)在正在运行的服务器上。

3.  为源和目标密钥库加载密钥环组件库。

4.  将源密钥库中的密钥复制到目标。

5.  卸载源和目标密钥库的密钥环组件库。

6.  （仅限在线迁移）启用[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)在正在运行的服务器上。

7.  （仅限在线迁移）断开与正在运行的服务器的连接。

    如果在密钥迁移期间发生错误，则目标密钥库将恢复到其迁移前状态。

    成功进行在线密钥迁移操作后，可能需要重新启动正在运行的服务器：

-   如果正在运行的服务器在迁移之前正在使用源密钥库，并且应该在迁移后继续使用它，则迁移后无需重新启动它。

-   如果正在运行的服务器在迁移之前正在使用目标密钥库，并且应该在迁移之后继续使用它，则应该在迁移后重新启动以加载所有迁移到目标密钥库中的密钥。

-   如果正在运行的服务器在迁移之前使用源密钥库，但在迁移之后应该使用目标密钥库，则必须将其重新配置为使用目标密钥库并重新启动。在这种情况下，请注意，虽然正在运行的服务器在迁移过程中暂停修改源密钥库，但在迁移和后续重启之间的时间间隔内不会暂停。应注意服务器在此间隔期间不要修改源密钥库，因为任何此类更改都不会反映在目标密钥库中。

##### 涉及多个正在运行的服务器的密钥迁移

在线密钥迁移提供在单个正在运行的服务器上暂停密钥环操作。如果多个正在运行的服务器正在使用所涉及的密钥库，要执行迁移，请使用以下过程：

1.  手动连接到每个正在运行的服务器并设置[`密钥环操作=关闭`](keyring-system-variables.html#sysvar_keyring_operations).这可确保没有正在运行的服务器使用源或目标密钥库，并满足脱机迁移所需的条件。

2.  使用迁移服务器或[**mysql\_迁移\_钥匙圈**](mysql-migrate-keyring.html)为每个暂停的服务器执行离线密钥迁移。

3.  手动连接到每个正在运行的服务器并设置[`keyring_operations=开启`](keyring-system-variables.html#sysvar_keyring_operations).

    所有正在运行的服务器必须支持[`密钥环操作`](keyring-system-variables.html#sysvar_keyring_operations)系统变量。任何不需要的服务器都必须在迁移之前停止并在之后重新启动。
