Using the Keyring Component or Keyring Plugin¶
This software documentation is (C)2009-2018 Percona LLC and/or its affiliates and is distributed under the Creative Commons Attribution-ShareAlike 2.0 Generic license.
The keyring_vault
plugin can store the encryption keys inside the HashiCorp Vault.
Note
See also Installing Vault and Production Hardening.
Galera can use either of the following plugins:
keyring_file
stores the keyring data locallykeyring_vault
provides an interface for the database with a HashiCorp Vault server to store key and secure encryption keys.
Note
Do not use the keyring_file
plugin for regulatory compliance.
To install the plugin, follow the installing and uninstalling plugins instructions.
Loading the Keyring Plugin
Load the plugin at server startup with the -early-plugin-load
option to enable keyrings.
Warning
Only enable one keyring plugin at a time. Enabling multiple keyring plugins is not supported and may result in data loss.
We recommend that you load the plugin in the configuration file to facilitate recovery for encrypted tables. Also, the redo log encryption and the undo log encryption cannot be used without --early-plugin-load
. The normal plugin load happens too late in startup.
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 the file location in your operating system.
To use the keyring_vault
, you can add this option to your configuration file:
You can also run the following command, which loads the keyring_file
plugin:
$ mysqld --early-plugin-load="keyring_file=keyring_file.so"
Note
If a server starts 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 addresssecret_mount_point
- the mount point name wherekeyring_vault
stores the keys.secret_mount_point_version
- the KV Secrets Engine version (kv or kv-v2) used.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
secret_mount_point_version = AUTO
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 servers 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.
secret_mount_point_version
The secret_mount_point_version
can be either 1
, 2
, AUTO
, or the secret_mount_point_version
parameter is not listed in the configuration file.
Value | Description |
---|---|
1 |
Works with KV Secrets Engine - Version 1 (kv). When forming key operation URLs, the secret_mount_point is always used without any transformations. For example, to return a key named skey, the URL is /v1//skey . |
2 |
Works with KV Secrets Engine - Version 2 (kv) The initialization logic splits the secret_mount_point parameter into two parts:
For example, both the |
AUTO |
An autodetection mechanism probes and determines if the secrets engine version is kv or kv-v2 and based on the outcome will either use the secret_mount_point as is, or split the secret_mount_point into two parts. |
Not listed | If the secret_mount_point_version is not listed in the configuration file, the behavior is the same as with AUTO . |
If you set the secret_mount_point_version
to 2, but the path pointed by secret_mount_point
is based on KV Secrets Engine - Version 1 (kv), an error is reported and the plugin fails to initialize.
If you set the secret_mount_point_version
to 1 but the path pointed by secret_mount_point
is based on KV Secrets Engine - Version 2 (kv-v2), the plugin initialization succeeds but any MySQL keyring-related operations fail.
Upgrading from 8.0.22-13 or earlier to 8.0.23-14 or later
The keyring_vault
plugin configuration files created before Galera Cluster for MySQL 8.0.23-14 work only with KV Secrets Engine - Version 1 (kv) and do not have the secret_mount_point_version
parameter. After the upgrade to 8.0.23-14 or later, the secret_mount_point_version
is implicitly considered AUTO
and the information is probed and the secrets engine version is determined to 1
.
Upgrading from Vault Secrets Engine Version 1 to Version 2
You can upgrade from the Vault Secrets Engine Version 1 to Version 2. Use either of the following methods:
- Set the
secret_mount_point_version
toAUTO
or the variable is not set in thekeyring_vault plugin
configuration files in all Galera servers. TheAUTO
value ensures the autodetection mechanism is invoked during the plugin initialization. - Set the
secret_mount_point_version
to2
to ensure that plugins do not initialize unless thekv
tokv-v2
upgrade completes.
Note
The keyring_vault
plugin that works with kv-v2
secret engines does not use the built-in key versioning capabilities. The keyring key versions are encoded into key names.
This feature enables using secondary groups in the mapping part of the authentication string, like “mysql, developers=joe, dba=mark
”. Previously, only primary groups could have been specified there. If user is a member of both developers
and dba
, the PAM plugin will map it to joe
, as developers
matches first.
KV Secret Engine considerations for upgrading from 5.7 to 8.0
When you upgrade from Galera Cluster for MySQL 5.7.32 or older, you can only use KV Secrets Engine 1 (kv)
. You can upgrade to any version of Percona Server for MySQL 8.0. Both the old keyring_vault
plugin and new keyring_vault
plugin work correctly with the existing Vault Server data under the existing keyring_vault
plugin configuration file.
If you upgrade from Galera Cluster for MySQL 5.7.33 or newer, you have the following options:
- If you are using
KV Secrets Engine 1 (kv)
you can upgrade with any version of Galera Cluster for MySQL 8.0. - If you are using
KV Secrets Engine 2 (kv-v2)
you can upgrade with Galera Cluster for MySQL 8.0.23 or newer. Galera Cluster for MySQL 8.0.23.14 is the first version of the 8.0 series which has thekeyring_vault
plugin that supportskv-v2
.
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 the General-Purpose Keyring Key-Management Functions manual.
The plugin library contains keyring user-defined functions which allow access to the internal keyring service functions. To enable the functions, you must enable the keyring_udf
plugin:
$ mysqld INSTALL PLUGIN keyring_udf SONAME 'keyring_udf.so';
Note
The keyring_udf
plugin must be installed. Using the user-defined functions without the keyring_udf
plugin generates an error.
You must also create keyring encryption user-defined functions.
Using the keyring_file component
See keyring component installation for information on installing the component.
Warning
Do not use the keyring_file
component for regulatory compliance.
Note
See also MySQL Documentation: Using the keyring_file component.
System Variables
keyring_vault_config
This variable defines the location of the keyring_vault_plugin
configuration file.
Command Line | –keyring-vault-config |
Scope | Global |
Dynamic | Yes |
Data Type | Text |
keyring_vault_timeout
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
.
Command Line | –keyring_vault_timeout |
Scope | Global |
Dynamic | Yes |
Data Type | Numeric |
Default | 15 |
Related Documents