Overview

MySQL Heatwave supports migration of keys between keyring keystores, enabling DBAs to switch a MySQL installation from one keyring keystore to another. The keyring manages keystores using keyring components and keyring plugins. Before 8.4.0 release MySQL Heatwave supported the following types of keyring migrations:

• From one keyring plugin to another
• From one keyring component to another, and
• From a keyring plugin to a keyring component.

There were no provision for migration from a keyring component to a keyring plugin.

With MySQL 8.4.0 we have extended keyring migration feature to support migration from a keyring component to a keyring plugin.

Keyring migration is supported either through a migration server or mysql_migrate_keyring utility based on the type of migration. Keyring component to plugin migration is possible through the migration server.

Keyring component to plugin migration using a migration server

A MySQL server becomes a migration server if invoked in a special operational mode that supports key migration. A migration server does not accept client connections. Instead, it runs only long enough to migrate keys, then exits.

The following key migration options are required for keyring component to keyring plugin migration:

• --keyring-migration-source: The source keyring component that manages the keys to be migrated.
• --keyring-migration-destination: The destination keyring plugin to which the migrated keys are to be copied.
• --keyring-migration-from-component: This option is required for migration from keyring component to plugin.

The --keyring-migration-source and --keyring-migration-destination options signify to the server that it should run in key migration mode. For key migration operations, both options are mandatory. Each plugin or component is specified using the name of its library file, including any platform-specific extension such as .so or .dll. The source and destination must differ, and the migration server must support them both.

For an ofline migration, no additional key migration options are needed.

For an online migration (i.e. some running server currently is using the source or destination keystore), specify additional options that indicate how to connect to the running server and pause keyring use during the migration operation. These options are:

• --keyring-migration-host: The host where the running server is located. This is always the local host because the migration server can migrate keys only between keystores managed by local plugins and components.
• --keyring-migration-user, --keyring-migration-password: The account credentials 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.

Online key migration using a migration server is only supported if the running server allows socket connections or TCP/IP connections using TLS; it is not supported when, for example, the server is running on a Windows platform and only allows shared memory connections.

For additional details about the key migration options, see Keyring Command Options.

Other server options might be required, such as configuration parameters for the keyring plugin. For example, if keyring_okv is the destination, you must set the keyring_okv_conf_dir system variable. 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.

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 migration from a keyring component to a keyring plugin:

mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-from-component
  --keyring-migration-source=component_keyring_encrypted_file.so
  --keyring-migration-destination=keyring_okv.so
  --keyring-okv-conf-dir=/usr/local/mysql/mysql-keyring-okv

Notice that no configuration options for the component is specified. The configuration options for the component are listed in the component configuration file. For details on configuration file for specific keyring component visit The MySQL Keyring.

Example command line for online migration from a keyring component to a keyring plugin:

mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-from-component
  --keyring-migration-source=component_keyring_encrypted_file.so
  --keyring-migration-destination=keyring_okv.so
  --keyring-okv-conf-dir=/usr/local/mysql/mysql-keyring-okv
  --keyring-migration-host=127.0.0.1
  --keyring-migration-user=root
  --keyring-migration-password=root_password

The key migration server performs a migration operation as follows:

If an error occurs during key migration, the destination keystore is restored to its premigration state.

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

Conclusion

With MySQL 8.4.0 it is possible to perform keyring migration from a keyring component to a keyring plugin using a migration server.

Thank you for using MySQL!