6.4 The MySQL Keyring

6.4.1 Keyring Plugin Installation

6.4.2 Using the keyring_file File-Based Keyring Plugin

6.4.3 Using the keyring_encrypted_file File-Based Keyring Plugin

6.4.4 Using the keyring_okv KMIP Plugin

6.4.5 Using the keyring_aws Amazon Web Services Keyring Plugin

6.4.6 Using the HashiCorp Vault Keyring Plugin

6.4.7 Using the Oracle Cloud Infrastructure Vault Keyring Plugin

6.4.8 Supported Keyring Key Types and Lengths

6.4.9 Migrating Keys Between Keyring Keystores

6.4.10 General-Purpose Keyring Key-Management Functions

6.4.11 Plugin-Specific Keyring Key-Management Functions

6.4.12 Keyring Metadata

6.4.13 Keyring Command Options

6.4.14 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 comprises these elements:

• Keyring plugins that manage a backing store or communicate with a storage back end. These keyring plugins are available:

  • keyring_file: Stores keyring data in a file local to the server host. Available in MySQL Community Edition and MySQL Enterprise Edition distributions. See Section 6.4.2, “Using the keyring_file File-Based Keyring Plugin”.

  • keyring_encrypted_file: Stores keyring data in an encrypted, password-protected file local to the server host. Available in MySQL Enterprise Edition distributions. See Section 6.4.3, “Using the keyring_encrypted_file File-Based Keyring Plugin”.

  • keyring_okv: 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. Available in MySQL Enterprise Edition distributions. See Section 6.4.4, “Using the keyring_okv KMIP Plugin”.

  • keyring_aws: Communicates with the Amazon Web Services Key Management Service for key generation and uses a local file for key storage. Available in MySQL Enterprise Edition distributions. See Section 6.4.5, “Using the keyring_aws Amazon Web Services Keyring Plugin”.

  • keyring_hashicorp: Communicates with HashiCorp Vault for back end storage. Available in MySQL Enterprise Edition distributions as of MySQL 8.0.18. See Section 6.4.6, “Using the HashiCorp Vault Keyring Plugin”.

  • keyring_oci: Communicates with Oracle Cloud Infrastructure Vault for back end storage. Available in MySQL Enterprise Edition distributions as of MySQL 8.0.22. See Section 6.4.7, “Using the Oracle Cloud Infrastructure Vault Keyring Plugin”.

• A keyring service interface for keyring key management. This service is accessible at two levels:

  • SQL interface: In SQL statements, call the user-defined functions (UDFs) described in Section 6.4.10, “General-Purpose Keyring Key-Management Functions”.

  • C interface: In C-language code, call the keyring service functions described in The Keyring Service.

• Key metadata access. The Performance Schema 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. Available as of MySQL 8.0.16. See The keyring_keys table.

• A key migration capability. MySQL supports migration of keys between underlying keystores, enabling DBAs to switch a MySQL installation from one keystore to another. See Section 6.4.9, “Migrating Keys Between Keyring Keystores”.

Warning

For encryption key management, the keyring_file and keyring_encrypted_file plugins 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).

Within MySQL, keyring service consumers include:

• The InnoDB storage engine uses the keyring to store its key for tablespace encryption. See InnoDB Data-at-Rest Encryption.

• MySQL Enterprise Audit uses the keyring to store the audit log file encryption password. See Encrypting Audit Log Files.

• Binary log and relay log management supports keyring-based encryption of log files. With log file encryption activated, the keyring stores the keys used to encrypt passwords for the binary log files and relay log files. See Encrypting Binary Log Files and Relay Log Files.

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

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

Keyring plugins and UDFs access a keyring service that provides the interface to the keyring. For information about accessing this service and writing keyring plugins, see The Keyring Service, and Writing Keyring Plugins.