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.
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
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
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"
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"
Only one keyring plugin should be enabled at a time. Enabling multiple keyring plugins is not supported and may result in data loss.
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
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
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
mysql> INSTALL PLUGIN keyring_udf SONAME 'keyring_udf.so';
keyring_udf plugin must be installed. Attempts to use the UDFs
keyring_udf plugin generates an error.
You must also create keyring encryption UDFs.
Dynamic: Yes Scope: Global Variable Type: Text Default Value:
This variable is used to define the location of the Loading the Keyring Plugin configuration file.
Dynamic: Yes Scope: Global Variable Type: Numeric Default Value:
Set the duration in seconds for the Vault server connection timeout. The
default value is
15. The allowed range is from
timeout can be also disabled to wait an infinite amount of time by setting
this variable to