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.
See also
- MySQL Documentation:
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 addresssecret_mount_point
- the mount point name where the keyring_vault- stores the keys
token
- a token generated by the Vault servervault_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
.
Contact Us
For free technical help, visit the Percona Community Forum.To report bugs or submit feature requests, open a JIRA ticket.
For paid support and managed or professional services, contact Percona Sales.