8.4.4.14 Migrating Keys Between Keyring Keystores

A keyring migration copies keys from one keystore to another, enabling a DBA to switch a MySQL installation to a different keystore. A successful migration operation has this result:

• The destination keystore contains the keys it had prior to the migration, plus the keys from the source keystore.

• The source keystore remains 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 keyring manages keystores using keyring components and keyring plugins. This pertains to migration strategy because the way in which the source and destination keystores are managed determines whether a particular type of key migration is possible and the procedure for performing it:

• Migration from one keyring plugin to another: The MySQL server has an operational mode that provides this capability.

• Migration from a keyring plugin to a keyring component: The MySQL server has an operational mode that provides this capability as of MySQL 8.0.24.

• Migration from one keyring component to another: The mysql_migrate_keyring utility provides this capability. mysql_migrate_keyring is available as of MySQL 8.0.24.

• Migration from a keyring component to a keyring plugin: There is no provision for this capability.

The following sections discuss the characteristics of offline and online migrations and describe how to perform migrations.

• Offline and Online Key Migrations

• Key Migration Using a Migration Server

• Key Migration Using the mysql_migrate_keyring Utility

• Key Migration Involving Multiple Running Servers

Offline and Online Key Migrations

A key migration is either offline or online:

• Offline migration: For use when you are sure that no running server on the local host is using the source or destination keystore. In this case, the migration operation can copy keys from the source keystore to the destination without the possibility of a running server modifying keystore content during the operation.

• Online migration: For use when a running server on the local host is using the source keystore. In this case, care must be taken to prevent that server from updating keystores during the migration. This involves connecting to the running server and instructing it to pause keyring operations so that keys can be copied safely from the source keystore to the destination. When key copying is complete, the running server is permitted to resume keyring operations.

When you plan a key migration, use these points to decide whether it should be offline or online:

• Do not perform offline migration involving a keystore that is in use by a running server.

• Pausing keyring operations during an online migration is accomplished by connecting to the running server and setting its global keyring_operations system variable to OFF before key copying and ON after key copying. This has several implications:

  • keyring_operations was introduced in MySQL 5.7.21, so online migration is possible only if the running server is from MySQL 5.7.21 or higher. If the running server is older, you must stop it, perform an offline migration, and restart it. All migration instructions elsewhere that refer to keyring_operations are subject to this condition.

  • The account used to connect to the running server must have the privileges required to modify keyring_operations. These privileges are ENCRYPTION_KEY_ADMIN in addition to either SYSTEM_VARIABLES_ADMIN or the deprecated SUPER privilege.

  • If an online migration operation exits abnormally (for example, if it is forcibly terminated), it is possible for keyring_operations to remain disabled 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 using this statement:

    SET GLOBAL keyring_operations = ON;

• Online key migration provides for pausing keyring operations on a single running server. To perform a migration if multiple running servers are using the keystores involved, use the procedure described at Key Migration Involving Multiple Running Servers.

Key Migration Using a Migration Server

Note

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.

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. A migration server reports errors to the console (the standard error output).

A migration server supports these migration types:

• Migration from one keyring plugin to another.

• Migration from a keyring plugin to a keyring component. This capability is available as of MySQL 8.0.24. Older servers support only migration from one keyring plugin to another, in which case the parts of these instructions that refer to keyring components do not apply.

A migration server does not support migration from one keyring component to another. For that type of migration, see Key Migration Using the mysql_migrate_keyring Utility.

To perform a key migration operation using a migration server, determine the key migration options required to specify which keyring plugins or components are involved, and whether the migration is offline or online:

• To indicate the source keyring plugin and the destination keyring plugin or component, specify these options:

  • --keyring-migration-source: The source keyring plugin that manages the keys to be migrated.

  • --keyring-migration-destination: The destination keyring plugin or component to which the migrated keys are to be copied.

  • --keyring-migration-to-component: This option is required if the destination is a keyring component rather than a keyring 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 offline migration, no additional key migration options are needed.

• For an online migration, some running server currently is using the source or destination keystore. To invoke the migration server, specify additional 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 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.

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

Start the migration server with key migration options indicating the source and destination keystores and whether the migration is offline or online, possibly with other options. Keep the following considerations in mind:

• Other server options might be required, such as configuration parameters for the two keyring plugins. For example, if keyring_file is the source or destination, 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.

• The migration server expects path name option values to be full paths. Relative path names may not be resolved as you expect.

• The user who invokes a server in key-migration mode must not be the root operating system user, unless the --user option is specified with a non-root user name to run the server as that user.

• The user a server in key-migration mode runs as must have permission to read and write any local keyring files, such as the data file for a file-based plugin.

  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. Alternatively, after the migration, examine the keyring-related file system objects and change their ownership and permissions if necessary using chown, chmod, or similar commands, so that the objects are accessible to the running server.

Example command line for offline migration between two keyring plugins (enter the command on a single line):

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 migration between two keyring plugins:

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

To perform a migration when the destination is a keyring component rather than a keyring plugin, specify the --keyring-migration-to-component option, and name the component as the value of the --keyring-migration-destination option.

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

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

Notice that in this case, no keyring_encrypted_file_password value is specified. The password for the component data file is listed in the component configuration file.

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

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

The key migration server performs a migration operation as follows:

1. (Online migration only) Connect to the running server using the connection options.

2. (Online migration only) Disable keyring_operations on the running server.

3. Load the keyring plugin/component libraries for the source and destination keystores.

4. Copy keys from the source keystore to the destination.

5. Unload the keyring plugin/component libraries for the source and destination keystores.

6. (Online migration only) Enable keyring_operations on the running server.

7. (Online migration only) Disconnect from the running server.

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:

• If the running server was using the source keystore before the migration and should continue to use it after the migration, it need not be restarted after the migration.

• If the running server was using the destination keystore before the migration and should continue to use it after the migration, it should be restarted after the migration to load all keys migrated into the destination keystore.

• 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 keystore and restarted. In this case, be aware that although the running server is paused from modifying the source keystore during the migration itself, it is not paused during the interval between the migration and the subsequent restart. Care should be taken that the server does not modify the source keystore during this interval because any such changes will not be reflected in the destination keystore.

Key Migration Using the mysql_migrate_keyring Utility

The mysql_migrate_keyring utility migrates keys from one keyring component to another. It does not support migrations involving keyring plugins. For that type of migration, use a MySQL server operating in key migration mode; see Key Migration Using a Migration Server.

To perform a key migration operation using mysql_migrate_keyring, determine the key migration options required to specify which keyring components are involved, and whether the migration is offline or online:

• To indicate the source and destination keyring components and their location, specify these options:

  • --source-keyring: The source keyring component that manages the keys to be migrated.

  • --destination-keyring: The destination keyring component to which the migrated keys are to be copied.

  • --component-dir: The directory containing keyring component library files. This is typically the value of the plugin_dir system variable for the local MySQL server.

  All three options are mandatory. Each keyring component name is a component library file name specified without any platform-specific extension such as .so or .dll. For example, to use the component for which the library file is component_keyring_file.so, specify the option as --source-keyring=component_keyring_file. The source and destination must differ, and mysql_migrate_keyring must support them both.

• For an offline migration, no additional options are needed.

• For an online migration, some running server currently is using the source or destination keystore. In this case, specify the --online-migration option to signify an online migration. In addition, specify connection options indicating how to connect to the running server, so that mysql_migrate_keyring can connect to it and tell it to pause keyring use during the migration operation.

  The --online-migration option is commonly used in conjunction with connection options such as these:

  • --host: The host where the running server is located. This is always the local host because mysql_migrate_keyring can migrate keys only between keystores managed by local components.

  • --user, --password: The account credentials to use to connect to the running server.

  • --port: For TCP/IP connections, the port number to connect to on the running server.

  • --socket: For Unix socket file or Windows named pipe connections, the socket file or named pipe to connect to on the running server.

For descriptions of all available options, see Section 6.6.8, “mysql_migrate_keyring — Keyring Key Migration Utility”.

Start mysql_migrate_keyring with options indicating the source and destination keystores and whether the migration is offline or online, possibly with other options. Keep the following considerations in mind:

• The user who invokes mysql_migrate_keyring must not be the root operating system user.

• The user who invokes mysql_migrate_keyring must have permission to read and write any local keyring files, such as the data file for a file-based plugin.

  If you invoke mysql_migrate_keyring 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 mysql_migrate_keyring while logged in as isabel. Any new directories or files created by mysql_migrate_keyring 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, invoke mysql_migrate_keyring as the mysql operating system user. Alternatively, after the migration, examine the keyring-related file system objects and change their ownership and permissions if necessary using chown, chmod, or similar commands, so that the objects are accessible to the running server.

Suppose that you want to migrate keys from component_keyring_file to component_keyring_encrypted_file, and that the local server stores its keyring component library files in /usr/local/mysql/lib/plugin.

If no running server is using the keyring, an offline migration is permitted. Invoke mysql_migrate_keyring like this (enter the command on a single line):

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

If a running server is using the keyring, you must perform an online migration instead. In this case, the --online-migration option must be given, along with any connection options required to specify which server to connect to and the MySQL account to use.

The following command performs an online migration. It connects to the local server using a TCP/IP connection and the admin account. The command prompts for a password, which you should enter when prompted:

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_migrate_keyring performs a migration operation as follows:

1. (Online migration only) Connect to the running server using the connection options.

2. (Online migration only) Disable keyring_operations on the running server.

3. Load the keyring component libraries for the source and destination keystores.

4. Copy keys from the source keystore to the destination.

5. Unload the keyring component libraries for the source and destination keystores.

6. (Online migration only) Enable keyring_operations on the running server.

7. (Online migration only) Disconnect from the running server.

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:

• If the running server was using the source keystore before the migration and should continue to use it after the migration, it need not be restarted after the migration.

• If the running server was using the destination keystore before the migration and should continue to use it after the migration, it should be restarted after the migration to load all keys migrated into the destination keystore.

• 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 keystore and restarted. In this case, be aware that although the running server is paused from modifying the source keystore during the migration itself, it is not paused during the interval between the migration and the subsequent restart. Care should be taken that the server does not modify the source keystore during this interval because any such changes will not be reflected in the destination keystore.

Key Migration Involving Multiple Running Servers

Online key migration provides for pausing keyring operations on a single running server. To perform a migration if multiple running servers are using the keystores involved, use this procedure:

1. Connect to each running server manually and set keyring_operations=OFF. This ensures that no running server is using the source or destination keystore and satisfies the required condition for offline migration.

2. Use a migration server or mysql_migrate_keyring to perform an offline key migration for each paused server.

3. Connect to each running server manually and set keyring_operations=ON.

All running servers must support the keyring_operations system variable. Any server that does not must be stopped before the migration and restarted after.