This is the third article in the series dedicated on transition from keyring plugins to keyring components. In the previous article we have discussed component_keyring_file (file-based keyring component), how different is it from the keyring_file plugin and how to install it using a manifest and configuration file. In this post we will be discussing component_keyring_encrypted_file keyring component, how different is it from keyring_encrypted_file plugin and the steps to install it.

Introduction

The component_keyring_encrypted_file keyring component, like keyring_encrypted_file plugin stores keyring data in an encrypted, password-protected file local to the server host.  However, the file format in which the keys are stored in the file are not the same. So, the same file cannot be used for both the plugin and the component. Therefore, one need to perform migration using migration server to switch from keyring_encrypted_file plugin to component_keyring_encrypted_file as discussed in the first article in this series.

Loading the component

Unlike keyring plugins, keyring components are not loaded using the --early-plugin-load server option or configured using system variables. Instead, the server determines which keyring component to load during startup using a manifest file (named mysqld.my), and the loaded component consults its own configuration file when it initializes.

Keyring components should be loaded only by using a manifest file, not by using the INSTALL COMPONENT statement. Keyring components loaded using that statement may be available too late in the server startup sequence for certain components that use the keyring, such as InnoDB.

The Manifest file

The server attempts to read its global manifest file from the directory where the server is installed.
If the global manifest file indicates use of a local manifest file, the server attempts to read its local manifest file from the data directory.
Local manifest files permit setting up component loading for multiple instances of the server, such that loading instructions for each server instance are specific to a given data directory instance. This enables different MySQL instances to use different keyring components.
To use a global manifest file only, the file contents look like this:

{
  "components": "file://component_keyring_encrypted_file"
}

Alternatively, to use a global and local manifest file pair, the global file looks like this:

{
  "read_local_manifest": true
}

The local file looks like this:

{
  "components": "file://component_keyring_encrypted_file"
}

The Configuration File

The component attempts to read its global configuration file from the directory where the component library file is installed (that is, the server plugin directory).
If the global configuration file indicates use of a local configuration file, the component attempts to read its local configuration file from the data directory.
The file name is component_keyring_encrypted_file.cnf in both locations.
Local configuration files permit setting up multiple server instances to use component_keyring_encrypted_file, such that component configuration for each server instance is specific to a given data directory instance. This enables the same keyring component to be used with a distinct keyring data file for each instance.

To use a global configuration file only, the file contents look like this:

{
  "path": "/usr/local/mysql/keyring/component_keyring_encrypted_file",
  "password": "password",
  "read_only": false
}

where  "path" value is a string that names the file to use for storing keyring data, "password" value is a string that specifies the password for accessing the data file and "read_only" value indicates whether the keyring data file is read only.

Alternatively, to use a global and local configuration file pair, the global file looks like this:

{
  "read_local_config": true
}

The local file looks like this:

{
  "path": "/usr/local/mysql/keyring/component_keyring_encrypted_file",
  "password": "password",
  "read_only": false
}

Start the server with the manifest and configuration files in place as described above and you are good to go!

Verify component installation by examining the Performance Schema keyring_component_status table:

mysql> SELECT * FROM performance_schema.keyring_component_status;
+---------------------+-------------------------------------------------+
| STATUS_KEY          | STATUS_VALUE                                    |
+---------------------+-------------------------------------------------+
| Component_name      | component_keyring_encrypted_file                |
| Author              | Oracle Corporation                              |
| License             | PROPRIETARY                                     |
| Implementation_name | component_keyring_encrypted_file                |
| Version             | 1.0                                             |
| Component_status    | Active                                          |
| Data_file           | /usr/local/component_keyring_encrypted_file     |
| Read_only           | No                                              |
+---------------------+-------------------------------------------------+

A Component_status value of Active indicates that the component initialized successfully.

If the component cannot be loaded, server startup fails. Check the server error log for diagnostic messages. If the component loads but fails to initialize due to configuration problems, the server starts but the Component_status value is Disabled. Check the server error log, correct the configuration issues, and use the ALTER INSTANCE RELOAD KEYRING statement to reload the configuration.

To see which keys exist, check the Performance Schema keyring_keys table:

mysql> SELECT * FROM performance_schema.keyring_keys;
+-----------------------------+--------------+----------------+
| KEY_ID                      | KEY_OWNER    | BACKEND_KEY_ID |
+-----------------------------+--------------+----------------+
| audit_log-20210322T130749-1 |              |                |
| MyKey                       | me@localhost |                |
| YourKey                     | me@localhost |                |
+-----------------------------+--------------+----------------+

Conclusion

The component_keyring_encrypted_file keyring component is advanced, flexible and have fewer restrictions than the keyring_encrypted_file plugin. It can be loaded using the manifest and configuration file.

In the next article we will explore component_keyring_oci (Oracle Cloud Infrastructure Vault Keyring Component).