Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 37.5Mb
PDF (A4) - 37.5Mb
PDF (RPM) - 33.3Mb
HTML Download (TGZ) - 8.3Mb
HTML Download (Zip) - 8.3Mb
HTML Download (RPM) - 7.2Mb
Man Pages (TGZ) - 129.9Kb
Man Pages (Zip) - 185.5Kb
Info (Gzip) - 3.3Mb
Info (Zip) - 3.3Mb

MySQL 8.0 Reference Manual  /  ...  /  Keyring System Variables

Pre-General Availability Draft: 2018-03-17 Keyring System Variables

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, “Keyring Plugin Installation”).

  • keyring_file_data

    Property Value
    Command-Line Format --keyring-file-data=file_name
    System Variable keyring_file_data
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type file name
    Default 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.


    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 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_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_operations

    Property Value
    Introduced 8.0.4
    System Variable keyring_operations
    Scope Global
    Dynamic Yes
    SET_VAR Hint Applies No
    Type boolean
    Default ON

    Whether keyring operations are enabled. This variable is used during key migration operations. See Section, “Migrating Keys Between Keyring Keystores”. The privileges required to modify this variable are ENCRYPTION_KEY_ADMIN in addition to either SYSTEM_VARIABLES_ADMIN or SUPER.

User Comments
Sign Up Login You must be logged in to post a comment.