#### 6.4.4.3 Keyring Plugin Installation

[]()[]()[]()[]()[]()[]()[]()[]()[]()[]()[]()[]()

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

* To use a keyring plugin, begin with the instructions here. (Also, for general information about installing plugins, see [Section 5.6.1, “Installing and Uninstalling Plugins”](plugin-loading.html).)

* To use a keyring component instead, begin with [Section 6.4.4.2, “Keyring Component Installation”](keyring-component-installation.html).

* 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 6.4.4.14, “General-Purpose Keyring Key-Management Functions”](keyring-functions-general-purpose.html).

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 plugin choices:

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

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

* `keyring_okv`: A KMIP 1.1 plugin for use with KMIP-compatible back end keyring storage products such as Oracle Key Vault and Gemalto SafeNet KeySecure Appliance. Available in MySQL Enterprise Edition distributions.

* `keyring_aws`: Communicates with the Amazon Web Services Key Management Service as a back end for key generation and uses a local file for key storage. Available in MySQL Enterprise Edition distributions.

* `keyring_hashicorp`: Communicates with HashiCorp Vault for back end storage. Available in MySQL Enterprise Edition distributions.

* `keyring_oci`: Communicates with Oracle Cloud Infrastructure Vault for back end storage. See [Section 6.4.4.11, “Using the Oracle Cloud Infrastructure Vault Keyring Plugin”](keyring-oci-plugin.html).

 To be usable by the server, the plugin library file must be located in the MySQL plugin directory (the directory named by the [`plugin_dir`](server-system-variables.html#sysvar_plugin_dir) system variable). If necessary, configure the plugin directory location by setting the value of [`plugin_dir`](server-system-variables.html#sysvar_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.

 Installation for each keyring plugin is similar. The following instructions describe how to install `keyring_file`. To use a different keyring plugin, substitute its name for `keyring_file`.

 The `keyring_file` plugin library file base name is `keyring_file`. The file name suffix differs per platform (for example, `.so` for Unix and Unix-like systems, `.dll` for Windows).

 To load the plugin, use the [`--early-plugin-load`](server-options.html#option_mysqld_early-plugin-load) option to name the plugin library file that contains it. For example, on platforms where the plugin library file suffix is `.so`, use these lines in the server `my.cnf` file, adjusting the `.so` suffix for your platform as necessary:

```
[mysqld]
early-plugin-load=keyring_file.so
```

 Before starting the server, check the notes for your chosen keyring plugin for configuration instructions specific to that plugin:

* `keyring_file`: [Section 6.4.4.6, “Using the keyring\_file File-Based Keyring Plugin”](keyring-file-plugin.html).

* `keyring_encrypted_file`: [Section 6.4.4.7, “Using the keyring\_encrypted\_file Encrypted File-Based Keyring Plugin”](keyring-encrypted-file-plugin.html).

* `keyring_okv`: [Section 6.4.4.8, “Using the keyring\_okv KMIP Plugin”](keyring-okv-plugin.html).

* `keyring_aws`: [Section 6.4.4.9, “Using the keyring\_aws Amazon Web Services Keyring Plugin”](keyring-aws-plugin.html)

* `keyring_hashicorp`: [Section 6.4.4.10, “Using the HashiCorp Vault Keyring Plugin”](keyring-hashicorp-plugin.html)

* `keyring_oci`: [Section 6.4.4.11, “Using the Oracle Cloud Infrastructure Vault Keyring Plugin”](keyring-oci-plugin.html)

 After performing any plugin-specific configuration, start the server. Verify plugin installation by examining the [`INFORMATION_SCHEMA.PLUGINS`](information-schema-plugins-table.html) table or use the [`SHOW PLUGINS`](show-plugins.html) statement (see [Section 5.6.2, “Obtaining Server Plugin Information”](obtaining-plugin-information.html)). For example:

```
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
       FROM INFORMATION_SCHEMA.PLUGINS
       WHERE PLUGIN_NAME LIKE 'keyring%';
+--------------+---------------+
| PLUGIN_NAME  | PLUGIN_STATUS |
+--------------+---------------+
| keyring_file | ACTIVE        |
+--------------+---------------+
```

 If the plugin fails to initialize, check the server error log for diagnostic messages.

 Plugins can be loaded by methods other than [`--early-plugin-load`](server-options.html#option_mysqld_early-plugin-load), such as the [`--plugin-load`](server-options.html#option_mysqld_plugin-load) or [`--plugin-load-add`](server-options.html#option_mysqld_plugin-load-add) option or the [`INSTALL PLUGIN`](install-plugin.html) statement. However, keyring plugins loaded using those methods may be available too late in the server startup sequence for certain components that use the keyring, such as `InnoDB`:

* Plugin loading using [`--plugin-load`](server-options.html#option_mysqld_plugin-load) or [`--plugin-load-add`](server-options.html#option_mysqld_plugin-load-add) occurs after `InnoDB` initialization.

* Plugins installed using [`INSTALL PLUGIN`](install-plugin.html) are registered in the `mysql.plugin` system table and loaded automatically for subsequent server restarts. However, because `mysql.plugin` is an `InnoDB` table, any plugins 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. To ensure that `InnoDB` can access encrypted tablespaces as well, use [`--early-plugin-load`](server-options.html#option_mysqld_early-plugin-load) to load the keyring plugin.

