Pre-General Availability Draft: 2018-03-17
MySQL Keyring plugins support the following system variables. Use them to configure keyring plugin operation. These variables are unavailable unless the appropriate keyring plugin is installed (see Section 126.96.36.199, “Keyring Plugin Installation”).
Property Value Command-Line Format
Scope Global Dynamic Yes SET_VAR Hint Applies No Type file name Default
The path name of the data file used for secure data storage by the
keyring_fileplugin. This variable is unavailable unless that plugin is installed. The file location should be in a directory considered for use only by keyring plugins. For example, do not locate the file under the data directory.
Keyring operations are transactional: The
keyring_fileplugin uses a backup file during write operations to ensure that it can roll back to the original file if an operation fails. The backup file has the same name as the value of the
keyring_file_datasystem variable with a suffix of
Do not use the same
keyring_filedata file for multiple MySQL instances. Each instance should have its own unique data file.
The default file name is
keyring, located in a directory that is platform specific and depends on the value of the
INSTALL_LAYOUTCMake option, as shown in the following table. To specify the default directory for the file explicitly if you are building from source, use the
At plugin startup, if the value assigned to
keyring_file_dataspecifies a file that does not exist, the
keyring_fileplugin attempts to create it (as well as its parent directory, if necessary).
If you create the directory manually, it should have a restrictive mode and be accessible only to the account used to run the MySQL server. For example, on Unix and Unix-like systems, to use the
/usr/local/mysql/mysql-keyringdirectory, the following commands (executed as
root) create the directory and set its mode and ownership:
cd /usr/local/mysql mkdir mysql-keyring chmod 750 mysql-keyring chown mysql mysql-keyring chgrp mysql mysql-keyring
keyring_fileplugin cannot create or access its data file, it writes an error message to the error log. If an attempted runtime assignment to
keyring_file_dataresults in an error, the variable value remains unchanged.Important
keyring_fileplugin has created its data file and started to use it, it is important not to remove the file. For example,
InnoDBuses the file to store the master key used to decrypt the data in tables that use
InnoDBtablespace encryption; see Section 15.7.11, “InnoDB Tablespace Encryption”. Loss of the file will cause data in such tables to become inaccessible. (It is permissible to rename or move the file, as long as you change the value of
keyring_file_datato match.) It is recommended that you create a separate backup of the keyring data file immediately after you create the first encrypted table and before and after master key rotation.
Property Value Introduced 8.0.4 System Variable
Scope Global Dynamic Yes SET_VAR Hint Applies No Type boolean Default
Whether keyring operations are enabled. This variable is used during key migration operations. See Section 188.8.131.52, “Migrating Keys Between Keyring Keystores”. The privileges required to modify this variable are
ENCRYPTION_KEY_ADMINin addition to either