In this series of articles we will explore MySQL transition from keyring plugins to keyring components, the advantages of keyring components over keyring plugins, migration from keyring plugin to keyring component and steps to initialize and configure keyring components.

Motivation

Before MySQL 8.0, to add a feature to MySQL, writing a plugin was the only way. Now it’s possible to quickly extend MySQL Server by writing a component.

The MySQL Component Infrastructure is designed to overcome some of the architectural issues of the plugin subsystem, namely:

• plugins can only “talk” to the server and not with other plugins
• plugins have access to the server symbols and can call them directly (no encapsulation)
• there’s no explicit set of dependencies of a plugin, thus it’s hard to initialize them properly
• plugins require a running server to operate

The component infrastructure aims at allowing the MySQL server subsystems to be encapsulated into a set of logical components. Additional components may be added to a running server to extend its functionality.

MySQL Heatwave supports a keyring that enables internal server components and plugins to securely store sensitive information for later retrieval. These sensitive information include, InnoDB keys for tablespace encryption, audit log file encryption password, keys to encrypt passwords for the binary & relay log files and the master key to decrypt the file key that decrypts the persisted values of sensitive system variables.

The MySQL Keyring originally implemented keystore capabilities using server plugins, but began transitioning to use the component infrastructure in MySQL 8.0.24 to overcome plugin drawbacks and leverage the advantages that components provide. The introduction of keyring components (component_keyring_file & component_keyring_encrypted_file in MySQL 8.0.24 and component_keyring_oci in 8.0.31) and removal of corresponding keyring plugins (keyring_file, keyring_encryped_file and keyring_oci) in MySQL 8.4.0 is a continuation of that effort.

If you are using any of the above keyring plugins then this series of articles will help you choose and migrate to one of the available keyring components.

Keyring Components versus Keyring Plugins

Let’s compare keyring components and plugins to get an overview of their differences and see why you should consider switching.

• Keyring plugins are loaded using the --early-plugin-load option. Keyring component are loaded using a manifest file.
• Keyring plugin configuration is based on plugin-specific system variables. For keyring components, no system variables are used. Instead, each component has its own configuration file.
• Keyring components have fewer restrictions than keyring plugins with respect to key types and lengths.
• Keyring components support secure storage for persisted system variable values, whereas keyring plugins do not support the function. The sensitive data that can be protected in this way includes items such as private keys and passwords that appear in the values of system variables. In the operating system file where persisted system variables are stored, the names and values of sensitive system variables are stored in an encrypted format, along with a generated file key to decrypt them. The generated file key is in turn encrypted using a master key that is stored in a keyring.

Hence, keyring components are advanced, flexible and have fewer ristrictions than keyring plugins.

Migration from a keyring plugin to a keyring component

A keyring migration copies keys from one keystore to another, enabling a DBA to switch a MySQL installation to a different keystore. You can migrate from a keyring plugin to a keyring component 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 to specify which keyring plugins and components are involved, and whether the migration is offline or online:

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

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 can be:

• --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.

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

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_okv.so
  --keyring-okv-conf-dir=/usr/local/mysql/mysql-keyring-okv
  --keyring-migration-destination=component_keyring_encrypted_file.so

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

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

Once the migration is successful you can load the keyring component using the manifest and configuration file and start using it to store sensitive information. For steps to intialize and configure each keyring component visit the next articles in this series:

• Using the component_keyring_file File-Based Keyring Component in MySQL
• Using the component_keyring_encrypted_file Encrypted File-Based Keyring Component in MySQL
• Using the Oracle Cloud Infrastructure Vault Keyring Component in MySQL Heatwave

Conclusion

The keyring components are advanced, flexible and have fewer restrictions than the keyring plugins. And all it requires is a few simple steps to switch.

In the next article we will explore component_keyring_file (File-Based Keyring Component).