6.4.4.7 Migrating Keys Between Keyring Keystores

As of MySQL 5.7.21, the MySQL server supports an operational mode that enables migration of keys between underlying keyring keystores, permitting DBAs to switch a MySQL installation from one keyring plugin to another. A migration server (that is, a server started in key migration mode) does not accept client connections. Instead, it runs only long enough to migrate keys, then exits. A migration server reports errors to the console (the standard error output).

It is possible to perform offline or online key migration:

If you are sure that no running server on the local host is using the source or destination keystore, an offline migration is possible. In this case, the migration server can modify the keystores without possibility of a running server modifying keystore content during the migration.
If a running server on the local host is using the source or destination keystore, an online migration must be performed. In this case, the migration server connects to the running server and instructs it to pause keyring operations while key migration is in progress.

The result of a key migration operation is that the destination keystore contains the keys it had prior to the migration, plus the keys from the source keystore. The source keystore is the same before and after the migration because keys are copied, not moved. If a key to be copied already exists in the destination keystore, an error occurs and the destination keystore is restored to its premigration state.

The user who invokes the server in key-migration mode must not be the root operating system user, and must have permission to read and write the keyring files.

To perform a key migration operation, determine which key migration options are needed. Migration options indicate which keyring plugins are involved, and whether to perform an offline or online migration:

To indicate the source and destination keyring plugins, specify these options:
- --keyring-migration-source: The source keyring plugin that manages the keys to be migrated.
- --keyring-migration-destination: The destination keyring plugin to which the migrated keys are to be copied.
These options tell the server to run in key migration mode. Both options are mandatory for all key migration operations. The source and destination plugins must differ, and the migration server must support both plugins.
For an offline migration, no additional key migration options are needed.
Warning
Do not perform offline migration involving a keystore that is in use by a running server.
For an online migration, some running server currently is using the source or destination keystore. Specify the key migration options that indicate how to connect to the running server. This is necessary so that the migration server can connect to the running server and tell it to pause keyring use during the migration operation.
Use of any of the following options signifies an online migration:
- --keyring-migration-host: The host where the running server is located. This is always the local host.
- --keyring-migration-user, --keyring-migration-password: The user name and password for the account to use to connect to the running server.
- --keyring-migration-port: For TCP/IP connections, the port number to connect to on the running server.
- --keyring-migration-socket: For Unix socket file or Windows named pipe connections, the socket file or named pipe to connect to on the running server.

For additional details about the key migration options, see Section 6.4.4.10, “Keyring Command Options”.

Start the migration server with the key migration options determined as just described, possibly with other options. Keep the following considerations in mind:

Other server options might be required, such as other configuration parameters for the two keyring plugins. For example, if keyring_file is one of the plugins, you must set the keyring_file_data system variable if the keyring data file location is not the default location. Other non-keyring options may be required as well. One way to specify these options is by using --defaults-file to name an option file that contains the required options.
If you invoke the migration server from a system account different from that normally used to run MySQL, it might create keyring directories or files that are inaccessible to the server during normal operation. Suppose that mysqld normally runs as the mysql operating system user, but you invoke the migration server while logged in as isabel. Any new directories or files created by the migration server are owned by isabel. Subsequent startup fails when a server run as the mysql operating system user attempts to access file system objects owned by isabel.
To avoid this issue, start the migration server as the root operating system user and provide a --user=user_name option, where user_name is the system account normally used to run MySQL.
The migration server expects path name option values to be full paths. Relative path names may not be resolved as you expect.

Example command line for offline key migration:

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

Example command line for online key migration:

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=localhost
  --keyring-migration-user=root
  --keyring-migration-password=root_password

The key migration server performs the migration operation as follows:

(Online migration only) Connect to the running server using the connection options. The account used to connect must have the SUPER privilege required to modify the global keyring_operations system variable.
(Online migration only) Disable keyring_operations on the running server. (The running server must support keyring_operations, which means it must be from MySQL 5.7.21 or higher.)
Load the source and destination keyring plugins.
Copy keys from the source keyring to the destination keyring.
Unload the keyring plugins.
(Online migration only) Enable keyring_operations on the running server.
(Online migration only) Disconnect from the running server.
Exit.

If an error occurs during key migration, any keys that were copied to the destination plugin are removed, leaving the destination keystore unchanged.

Important

For an online migration operation, the migration server takes care of enabling and disabling keyring_operations on the running server. However, if the migration server exits abnormally (for example, if someone forcibly terminates it), it is possible that keyring_operations was not re-enabled on the running server, leaving it unable to perform keyring operations. In this case, it may be necessary to connect to the running server and enable keyring_operations manually.

After a successful online key migration operation, the running server might need to be restarted:

If the running server was using the source keystore, it need not be restarted after the migration.
If the running server was using the source keystore before the migration but should use the destination keystore after the migration, it must be reconfigured to use the destination keyring plugin and restarted.
If the running server was using the destination keystore and continues to use it, it should be restarted after the migration to load all keys migrated into the destination keystore.

Note

MySQL server key migration mode supports pausing a single running server. To perform a key migration if multiple key servers are using the keystores involved, use this procedure:

Connect to each running server manually and set keyring_operations=OFF.
Use the migration server to perform an offline key migration.
Connect to each running server manually and set keyring_operations=ON.

All running servers must support the keyring_operations=ON system variable.