8.4.4.2 Keyring Component Installation

Keyring service consumers require that a keyring component or plugin be installed:

• To use a keyring component, begin with the instructions here.

• To use a keyring plugin instead, begin with Section 8.4.4.3, “Keyring Plugin Installation”.

• If you intend to use keyring functions in conjunction with the chosen keyring component or plugin, install the functions after installing that component or plugin, using the instructions in Section 8.4.4.12, “General-Purpose Keyring Key-Management Functions”.

Note

Only one keyring component or plugin should be enabled at a time. Enabling multiple keyring components or plugins is unsupported and results may not be as anticipated.

MySQL provides these keyring component choices:

• component_keyring_file: Stores keyring data in a file local to the server host. Available in MySQL Community Edition and MySQL Enterprise Edition distributions.

• component_keyring_encrypted_file: Stores keyring data in an encrypted, password-protected file local to the server host. Available in MySQL Enterprise Edition distributions.

• component_keyring_oci: Stores keyring data in the Oracle Cloud Infrastructure Vault. Available in MySQL Enterprise Edition distributions.

To be usable by the server, the component library file must be located in the MySQL plugin directory (the directory named by the plugin_dir system variable). If necessary, configure the plugin directory location by setting the value of plugin_dir at server startup.

A keyring component or plugin must be loaded early during the server startup sequence so that other components can access it as necessary during their own initialization. For example, the InnoDB storage engine uses the keyring for tablespace encryption, so a keyring component or plugin must be loaded and available prior to InnoDB initialization.

Note

A keyring component must be enabled on the MySQL server instance if you need to support secure storage for persisted system variable values. The keyring plugin does not support the function. See Persisting Sensitive System Variables.

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, and the loaded component consults its own configuration file when it initializes. Therefore, to install a keyring component, you must:

1. Write a manifest that tells the server which keyring component to load.

2. Write a configuration file for that keyring component.

The first step in installing a keyring component is writing a manifest that indicates which component to load. During startup, the server reads either a global manifest file, or a global manifest file paired with a local 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.

• Although global and local manifest files are located in different directories, the file name is mysqld.my in both locations.

• It is not an error for a manifest file not to exist. In this case, the server attempts no component loading associated with the file.

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.

Server manifest files have these properties:

• A manifest file must be in valid JSON format.

• A manifest file permits these items:

  • "read_local_manifest": This item is permitted only in the global manifest file. If the item is not present, the server uses only the global manifest file. If the item is present, its value is true or false, indicating whether the server should read component-loading information from the local manifest file.

    If the "read_local_manifest" item is present in the global manifest file along with other items, the server checks the "read_local_manifest" item value first:

    • If the value is false, the server processes the other items in the global manifest file and ignores the local manifest file.

    • If the value is true, the server ignores the other items in the global manifest file and attempts to read the local manifest file.

  • "components": This item indicates which component to load. The item value is a string that specifies a valid component URN, such as "file://component_keyring_file". A component URN begins with file:// and indicates the base name of the library file located in the MySQL plugin directory that implements the component.

• Server access to a manifest file should be read only. For example, a mysqld.my server manifest file may be owned by root and be read/write to root, but should be read only to the account used to run the MySQL server. If the manifest file is found during startup to be read/write to that account, the server writes a warning to the error log suggesting that the file be made read only.

• The database administrator has the responsibility for creating any manifest files to be used, and for ensuring that their access mode and contents are correct. If an error occurs, server startup fails and the administrator must correct any issues indicated by diagnostics in the server error log.

Given the preceding manifest file properties, to configure the server to load component_keyring_file, create a global manifest file named mysqld.my in the mysqld installation directory, and optionally create a local manifest file, also named mysqld.my, in the data directory. The following instructions describe how to load component_keyring_file. To load a different keyring component, substitute its name for component_keyring_file.

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

  {
    "components": "file://component_keyring_file"
  }

  Create this file in the directory where mysqld is installed.

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

  {
    "read_local_manifest": true
  }

  Create this file in the directory where mysqld is installed.

  The local file looks like this:

  {
    "components": "file://component_keyring_file"
  }

  Create this file in the data directory.

With the manifest in place, proceed to configuring the keyring component. To do this, check the notes for your chosen keyring component for configuration instructions specific to that component:

• component_keyring_file: Section 8.4.4.4, “Using the component_keyring_file File-Based Keyring Component”.

• component_keyring_encrypted_file: Section 8.4.4.5, “Using the component_keyring_encrypted_file Encrypted File-Based Keyring Component”.

• component_keyring_oci: Section 8.4.4.9, “Using the Oracle Cloud Infrastructure Vault Keyring Component”.

After performing any component-specific configuration, start the server. 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_file                          |
| Author              | Oracle Corporation                              |
| License             | GPL                                             |
| Implementation_name | component_keyring_file                          |
| Version             | 1.0                                             |
| Component_status    | Active                                          |
| Data_file           | /usr/local/mysql/keyring/component_keyring_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.

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, because they are registered in the mysql.component system table and loaded automatically for subsequent server restarts. But mysql.component is an InnoDB table, so any components named in it can be loaded during startup only after InnoDB initialization.

If no keyring component or plugin is available when a component tries to access the keyring service, the service cannot be used by that component. As a result, the component may fail to initialize or may initialize with limited functionality. For example, if InnoDB finds that there are encrypted tablespaces when it initializes, it attempts to access the keyring. If the keyring is unavailable, InnoDB can access only unencrypted tablespaces.