Using the Keyring Plugin

Percona Server for MySQL may use the following plugins:

  • keyring_file stores the keyring data locally
  • keyring_vault provides an interface for the database with a HashiCorp Vault server to store key and secure encryption keys.

Note

The keyring_file plugin should not be used for regulatory compliance.

To install the plugin, follow the installing and uninstalling plugins instructions.

Loading the Keyring Plugin

You should load the plugin at server startup with the -early-plugin-load option to enable keyrings.

We recommend the plugin should be loaded in the configuration file to facilitate recovery for encrypted tables. Also, the redo log and undo log encryption cannot be used without --early-plugin-load. The normal plugin load happens too late in startup.

To use the keyring_vault, you can add this option to your configuration file:

[mysqld]
early-plugin-load="keyring_vault=keyring_vault.so"
loose-keyring_vault_config="/home/mysql/keyring_vault.conf"

Note

The keyring_vault extension, ”.so” and the file location for the vault configuration should be changed to match your operating system’s extension and operating system location.

You could also run the following command which loads the keyring_file plugin:

$ mysqld --early-plugin-load="keyring_file=keyring_file.so"

Warning

Only one keyring plugin should be enabled at a time. Enabling multiple keyring plugins is not supported and may result in data loss.

Note

If server is started with different plugins loaded early, the --early-plugin-load option should contain the plugin names in a double-quoted list with each plugin name separated by a semicolon. The use of double quotes ensures the semicolons do not create issues when the list is executed in a script.

Apart from installing the plugin you also must set the keyring_vault_config variable to point to the keyring_vault configuration file.

The keyring_vault_config file has the following information:

  • vault_url - the Vault server address
  • secret_mount_point - the mount point name where the keyring_vault
    stores the keys
  • token - a token generated by the Vault server
  • vault_ca [optional] - if the machine does not trust the Vault’s CA certificate, this variable points to the CA certificate used to sign the Vault’s certificates

This is an example of a configuration file:

vault_url = https://vault.public.com:8202
secret_mount_point = secret
token = 58a20c08-8001-fd5f-5192-7498a48eaf20
vault_ca = /data/keyring_vault_confs/vault_ca.crt

Warning

Each secret_mount_point must be used by only one server. If multiple server use the same secret_mount_point, the behavior is unpredictable.

The first time a key is fetched from a keyring, the keyring_vault communicates with the Vault server to retrieve the key type and data.

A user-created key deletion is only possible with the use of the keyring_udf plugin and deletes the key from the in-memory hash map and the Vault server. You cannot delete system keys, such as the master key.

This plugin supports the SQL interface for keyring key management described in General-Purpose Keyring Key-Management Functions manual.

The plugin library contains keyring user-defined functions (UDFs) which allow access to the internal keyring service functions. To enable the functions you must enable the keyring_udf plugin:

mysql> INSTALL PLUGIN keyring_udf SONAME 'keyring_udf.so';

Note

The keyring_udf plugin must be installed. Attempts to use the UDFs without the keyring_udf plugin generates an error.

You must also create keyring encryption UDFs.

System Variables

variable keyring_vault_config
Command Line:--keyring-vault-config
Dynamic:Yes
Scope:Global
Variable Type:Text
Default Value:

This variable is used to define the location of the Keyring Vault plugin configuration file.

variable keyring_vault_timeout
Command Line:--keyring-vault-timeout
Dynamic:Yes
Scope:Global
Variable Type:Numeric
Default Value:15

Set the duration in seconds for the Vault server connection timeout. The default value is 15. The allowed range is from 0 to 86400. The timeout can be also disabled to wait an infinite amount of time by setting this variable to 0.