6.4.4 The MySQL Keyring

6.4.4.1 Keyring Plugin Installation

6.4.4.2 Using the keyring_file File-Based Plugin

6.4.4.3 Using the keyring_encrypted_file Keyring Plugin

6.4.4.4 Using the keyring_okv KMIP Plugin

6.4.4.5 Using the keyring_aws Amazon Web Services Keyring Plugin

6.4.4.6 Using the HashiCorp Vault Keyring Plugin

6.4.4.7 Migrating Keys Between Keyring Keystores

6.4.4.8 Supported Keyring Key Types and Lengths

6.4.4.9 General-Purpose Keyring Key-Management Functions

6.4.4.10 Plugin-Specific Keyring Key-Management Functions

6.4.4.11 Keyring Command Options

6.4.4.12 Keyring System Variables

MySQL Server supports a keyring that enables internal server components and plugins to securely store sensitive information for later retrieval. The implementation is plugin-based:

• The keyring_file plugin stores keyring data in a file local to the server host. This plugin is available in all MySQL distributions, Community Edition and Enterprise Edition included. See Section 6.4.4.2, “Using the keyring_file File-Based Plugin”.

• The keyring_encrypted_file plugin stores keyring data in an encrypted file local to the server host. This plugin is available in MySQL Enterprise Edition distributions. See Section 6.4.4.3, “Using the keyring_encrypted_file Keyring Plugin”.

• keyring_okv is a KMIP 1.1 plugin for use with KMIP-compatible back end keyring storage products such as Oracle Key Vault and Gemalto SafeNet KeySecure Appliance. This plugin is available in MySQL Enterprise Edition distributions. See Section 6.4.4.4, “Using the keyring_okv KMIP Plugin”.

• The keyring_aws plugin communicates with the Amazon Web Services Key Management Service for key generation and uses a local file for key storage. This plugin is available in MySQL Enterprise Edition distributions. See Section 6.4.4.5, “Using the keyring_aws Amazon Web Services Keyring Plugin”.

• MySQL 8.0.18 and higher includes keyring_hashicorp, a plugin that communicates with HashiCorp Vault for back end storage. This plugin is available in MySQL Enterprise Edition distributions. See Section 6.4.4.6, “Using the HashiCorp Vault Keyring Plugin”.

• A MySQL server operational mode enables migration of keys between underlying keyring keystores. This enables DBAs to switch a MySQL installation from one keyring plugin to another. See Section 6.4.4.7, “Migrating Keys Between Keyring Keystores”.

• An SQL interface for keyring key management is implemented as a set of user-defined functions (UDFs). See Section 6.4.4.9, “General-Purpose Keyring Key-Management Functions”.

• In MySQL 8.0.16 and higher, the keyring_keys table exposes metadata for keys in the keyring. Key metadata includes key IDs, key owners, and backend key IDs. The keyring_keys table does not expose any sensitive keyring data such as key contents. See Section 26.12.18.2, “The keyring_keys table”.

Warning

The keyring_file and keyring_encrypted_file plugins for encryption key management are not intended as a regulatory compliance solution. Security standards such as PCI, FIPS, and others require use of key management systems to secure, manage, and protect encryption keys in key vaults or hardware security modules (HSMs).

Uses for the keyring within MySQL include:

• The InnoDB storage engine uses the keyring to store its key for tablespace encryption. InnoDB can use any supported keyring plugin.

• MySQL Enterprise Audit uses the keyring to store the audit log file encryption password. The audit log plugin can use any supported keyring plugin.

• When binary log encryption has been activated for a MySQL server (by setting binlog_encryption=ON), the binary log encryption keys used to encrypt the file passwords for the binary log files and relay log files are stored in the keyring. Any supported keyring plugin can be used to store binary log encryption keys. Binary log encryption keys are retained as long as there are files on the server that were encrypted using them. When the binary log master key is rotated manually, all binary log encryption keys that no longer apply to any retained binary log files or relay log files are cleared from the keyring. If a retained binary log file or relay log file cannot be initialized for re-encryption, the relevant binary log encryption keys are not deleted in case the files can be recovered in the future. For example, this might be the case if a file listed in a binary log index file is currently unreadable, or if a channel fails to initialize. For more information, see Section 17.3.2, “Encrypting Binary Log Files and Relay Log Files”.

For general keyring installation instructions, see Section 6.4.4.1, “Keyring Plugin Installation”. For information specific to a given keyring plugin, see the section describing that plugin.

For information about using the keyring UDFs, see Section 6.4.4.9, “General-Purpose Keyring Key-Management Functions”.

Keyring plugins and UDFs access a keyring service that provides the interface for server components to the keyring. For information about accessing the keyring plugin service and writing keyring plugins, see Section 29.3.2, “The Keyring Service”, and Section 29.2.4.12, “Writing Keyring Plugins”.