MySQL :: MySQL 5.7 Reference Manual :: 6.4.4.12 Keyring System Variables

keyring_aws_cmk_id

Command-Line Format	`--keyring-aws-cmk-id=value`
Introduced	5.7.19
System Variable	`keyring_aws_cmk_id`
Scope	Global
Dynamic	Yes
Type	String

The customer master key (CMK) ID obtained from the AWS KMS server and used by the keyring_aws plugin. This variable is unavailable unless that plugin is installed.

This variable is mandatory. If not specified, keyring_aws initialization fails.

keyring_aws_conf_file

Command-Line Format	`--keyring-aws-conf-file=file_name`
Introduced	5.7.19
System Variable	`keyring_aws_conf_file`
Scope	Global
Dynamic	No
Type	File name
Default Value	`platform specific`

The location of the configuration file for the keyring_aws plugin. This variable is unavailable unless that plugin is installed.

At plugin startup, keyring_aws reads the AWS secret access key ID and key from the configuration file. For the keyring_aws plugin to start successfully, the configuration file must exist and contain valid secret access key information, initialized as described in Section 6.4.4.5, “Using the keyring_aws Amazon Web Services Keyring Plugin”.

The default file name is keyring_aws_conf, located in the default keyring file directory. The location of this default directory is the same as for the keyring_file_data system variable. See the description of that variable for details, as well as for considerations to take into account if you create the directory manually.

keyring_aws_data_file

Command-Line Format	`--keyring-aws-data-file`
Introduced	5.7.19
System Variable	`keyring_aws_data_file`
Scope	Global
Dynamic	No
Type	File name
Default Value	`platform specific`

The location of the storage file for the keyring_aws plugin. This variable is unavailable unless that plugin is installed.

At plugin startup, if the value assigned to keyring_aws_data_file specifies a file that does not exist, the keyring_aws plugin attempts to create it (as well as its parent directory, if necessary). If the file does exist, keyring_aws reads any encrypted keys contained in the file into its in-memory cache. keyring_aws does not cache unencrypted keys in memory.

The default file name is keyring_aws_data, located in the default keyring file directory. The location of this default directory is the same as for the keyring_file_data system variable. See the description of that variable for details, as well as for considerations to take into account if you create the directory manually.

keyring_aws_region

Command-Line Format	`--keyring-aws-region=value`
Introduced	5.7.19
System Variable	`keyring_aws_region`
Scope	Global
Dynamic	Yes
Type	Enumeration
Default Value	`us-east-1`
Valid Values (≥ 5.7.39)	`af-south-1` `ap-east-1` `ap-northeast-1` `ap-northeast-2` `ap-northeast-3` `ap-south-1` `ap-southeast-1` `ap-southeast-2` `ca-central-1` `cn-north-1` `cn-northwest-1` `eu-central-1` `eu-north-1` `eu-south-1` `eu-west-1` `eu-west-2` `eu-west-3` `me-south-1` `sa-east-1` `us-east-1` `us-east-2` `us-gov-east-1` `us-iso-east-1` `us-iso-west-1` `us-isob-east-1` `us-west-1` `us-west-2`
Valid Values (≥ 5.7.27, ≤ 5.7.38)	`ap-northeast-1` `ap-northeast-2` `ap-south-1` `ap-southeast-1` `ap-southeast-2` `ca-central-1` `cn-north-1` `cn-northwest-1` `eu-central-1` `eu-west-1` `eu-west-2` `eu-west-3` `sa-east-1` `us-east-1` `us-east-2` `us-west-1` `us-west-2`
Valid Values (≥ 5.7.19, ≤ 5.7.26)	`ap-northeast-1` `ap-northeast-2` `ap-south-1` `ap-southeast-1` `ap-southeast-2` `eu-central-1` `eu-west-1` `sa-east-1` `us-east-1` `us-west-1` `us-west-2`

The AWS region for the keyring_aws plugin. This variable is unavailable unless that plugin is installed.

keyring_encrypted_file_data

Command-Line Format	`--keyring-encrypted-file-data=file_name`
Introduced	5.7.21
System Variable	`keyring_encrypted_file_data`
Scope	Global
Dynamic	Yes
Type	File name
Default Value	`platform specific`

The path name of the data file used for secure data storage by the keyring_encrypted_file plugin. 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_encrypted_file plugin 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_encrypted_file_data system variable with a suffix of .backup.

Do not use the same keyring_encrypted_file data file for multiple MySQL instances. Each instance should have its own unique data file.

The default file name is keyring_encrypted, located in a directory that is platform specific and depends on the value of the INSTALL_LAYOUT CMake option, as shown in the following table. To specify the default directory for the file explicitly if you are building from source, use the INSTALL_MYSQLKEYRINGDIR CMake option.

`INSTALL_LAYOUT` Value	Default `keyring_encrypted_file_data` Value
`DEB`, `RPM`, `SLES`, `SVR4`	`/var/lib/mysql-keyring/keyring_encrypted`
Otherwise	`keyring/keyring_encrypted` under the `CMAKE_INSTALL_PREFIX` value

At plugin startup, if the value assigned to keyring_encrypted_file_data specifies a file that does not exist, the keyring_encrypted_file plugin 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-keyring directory, 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

If the keyring_encrypted_file plugin cannot create or access its data file, it writes an error message to the error log. If an attempted runtime assignment to keyring_encrypted_file_data results in an error, the variable value remains unchanged.

Important

Once the keyring_encrypted_file plugin has created its data file and started to use it, it is important not to remove the file. Loss of the file causes data encrypted using its keys to become inaccessible. (It is permissible to rename or move the file, as long as you change the value of keyring_encrypted_file_data to match.)

keyring_encrypted_file_password

Command-Line Format	`--keyring-encrypted-file-password=password`
Introduced	5.7.21
System Variable	`keyring_encrypted_file_password`
Scope	Global
Dynamic	Yes
Type	String

The password used by the keyring_encrypted_file plugin. This variable is unavailable unless that plugin is installed.

This variable is mandatory. If not specified, keyring_encrypted_file initialization fails.

If this variable is specified in an option file, the file should have a restrictive mode and be accessible only to the account used to run the MySQL server.

Important

Once the keyring_encrypted_file_password value has been set, changing it does not rotate the keyring password and could make the server inaccessible. If an incorrect password is provided, the keyring_encrypted_file plugin cannot load keys from the encrypted keyring file.

The password value cannot be displayed at runtime with SHOW VARIABLES or the Performance Schema global_variables table because the display value is obfuscated.

keyring_file_data

Command-Line Format	`--keyring-file-data=file_name`
Introduced	5.7.11
System Variable	`keyring_file_data`
Scope	Global
Dynamic	Yes
Type	File name
Default Value	`platform specific`

The path name of the data file used for secure data storage by the keyring_file plugin. 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_file plugin 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_data system variable with a suffix of .backup.

Do not use the same keyring_file data 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_LAYOUT CMake option, as shown in the following table. To specify the default directory for the file explicitly if you are building from source, use the INSTALL_MYSQLKEYRINGDIR CMake option.

`INSTALL_LAYOUT` Value	Default `keyring_file_data` Value
`DEB`, `RPM`, `SLES`, `SVR4`	`/var/lib/mysql-keyring/keyring`
Otherwise	`keyring/keyring` under the `CMAKE_INSTALL_PREFIX` value

At plugin startup, if the value assigned to keyring_file_data specifies a file that does not exist, the keyring_file plugin 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-keyring directory, 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

If the keyring_file plugin cannot create or access its data file, it writes an error message to the error log. If an attempted runtime assignment to keyring_file_data results in an error, the variable value remains unchanged.

Important

Once the keyring_file plugin has created its data file and started to use it, it is important not to remove the file. For example, InnoDB uses the file to store the master key used to decrypt the data in tables that use InnoDB tablespace encryption; see Section 14.14, “InnoDB Data-at-Rest Encryption”. Loss of the file causes 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_data to 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.

keyring_okv_conf_dir

Command-Line Format	`--keyring-okv-conf-dir=dir_name`
Introduced	5.7.12
System Variable	`keyring_okv_conf_dir`
Scope	Global
Dynamic	Yes
Type	Directory name
Default Value	`empty string`

The path name of the directory that stores configuration information used by the keyring_okv plugin. This variable is unavailable unless that plugin is installed. The location should be a directory considered for use only by the keyring_okv plugin. For example, do not locate the directory under the data directory.

The default keyring_okv_conf_dir value is empty. For the keyring_okv plugin to be able to access Oracle Key Vault, the value must be set to a directory that contains Oracle Key Vault configuration and SSL materials. For instructions on setting up this directory, see Section 6.4.4.4, “Using the keyring_okv KMIP Plugin”.

The directory 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-keyring-okv directory, the following commands (executed as root) create the directory and set its mode and ownership:

cd /usr/local/mysql
mkdir mysql-keyring-okv
chmod 750 mysql-keyring-okv
chown mysql mysql-keyring-okv
chgrp mysql mysql-keyring-okv

If the value assigned to keyring_okv_conf_dir specifies a directory that does not exist, or that does not contain configuration information that enables a connection to Oracle Key Vault to be established, keyring_okv writes an error message to the error log. If an attempted runtime assignment to keyring_okv_conf_dir results in an error, the variable value and keyring operation remain unchanged.

keyring_operations

Introduced	5.7.21
System Variable	`keyring_operations`
Scope	Global
Dynamic	Yes
Type	Boolean
Default Value	`ON`

Whether keyring operations are enabled. This variable is used during key migration operations. See Section 6.4.4.7, “Migrating Keys Between Keyring Keystores”.