Use the Percona encrypted keyring file component

The component_percona_keyring_encrypted_file component stores encryption keys in a password-protected file on the server filesystem. The component is part of Percona Server for MySQL. After you load the keyring, you use the component for data at rest encryption the same way as other keyring components.

The Use the keyring file component page documents component_keyring_file. That component stores keyring data as plaintext JSON on disk. The component_percona_keyring_encrypted_file component encrypts the keyring file with a password that you provide.

Percona Server includes a separate component with its own on-disk format. A keyring file from MySQL Enterprise component_keyring_encrypted_file does not work with component_percona_keyring_encrypted_file.

Important

Load only one keyring at a time. Do not load component_percona_keyring_encrypted_file with component_keyring_file, legacy keyring plugins, or another keyring component.

Plan a migration before you switch keyrings if encrypted data already exists on the server. See Upgrade components and Migrate keyring data.

See Get Started with component keyring for a walkthrough of the unencrypted file keyring.

Version changes

Percona Server for MySQL 9.7 includes component_percona_keyring_encrypted_file from release 9.7.2.

Choose a file-based keyring component

Component	Keyring file on disk	Password required	Percona Server
component_keyring_file	Plaintext JSON	No	Yes
component_percona_keyring_encrypted_file	Encrypted (PBKDF2 + AES)	Yes	Yes

For key storage outside a local file, see these pages:

• Use the keyring vault component

• Use AWS KMS

• Use KMIP

Component installation

A keyring component loads at server startup from a manifest file. The component reads a JSON configuration file during initialization. Do not load a keyring component with INSTALL COMPONENT. InnoDB needs the keyring before the mysql.component table is available.

Available keyring components

Percona Server provides the following keyring components:

Component	Backend
component_keyring_file	Local file on disk
component_keyring_kmip	Key Management Interoperability Protocol (KMIP) server
component_keyring_kms	Cloud Key Management Service (KMS)
component_keyring_vault	HashiCorp Vault

Each component uses the same manifest mechanism. Each component reads its own configuration file. The name of the configuration file matches the component name with a .cnf

Create a global manifest file named mysqld.my in the directory that contains the mysqld binary. For multiple instances on one host, create a local manifest file with the same name in each data directory.

If the manifest file does not exist, the server does not load the keyring component. During startup, the server reads the global manifest from the installation directory. The global manifest can list the component directly or point to a local manifest in the data directory.

Manifest files

The manifest is a JavaScript Object Notation (JSON) object with the following fields:

Field	Type	Required	Description
components	string	Conditional	URL-style locator for the component to load. The format is file://<component_name>. Required when the manifest declares the component directly.
read_local_manifest	boolean	No	When true, the global manifest delegates to the local manifest in the data directory. When false or absent, the global manifest declares the component directly.

Manifest examples

Replace <component_name> in the following examples with one of the components in Available keyring components.

The following example shows a global manifest that loads a component directly:

{
  "components": "file://<component_name>"
}

The following example shows a global manifest that delegates to the local manifest:

{
  "read_local_manifest": true
}

The following example shows a local manifest:

{
  "components": "file://<component_name>"
}

Manifest locations

Percona Server reads two manifest files at startup:

Manifest	Location	Purpose
Global manifest	The directory that contains the mysqld binary	Default manifest for the server installation
Local manifest	Data directory	Per-instance override for hosts that run multiple instances with different keyring components

Both files use the name mysqld.my. The global manifest declares the component directly or delegates to the local manifest.

Why the manifest is the only supported load path

The keyring must load before InnoDB opens an encrypted page. Any mechanism that depends on the Structured Query Language (SQL) layer therefore loads the keyring too late.

A mysqld startup proceeds in the following order:

1. mysqld parses startup configuration and reads the manifest file from the server installation directory.

2. The server loads each component named in the manifest.

3. InnoDB initializes, replays the redo log, and opens tablespaces.

4. The SQL layer accepts connections.

The keyring must load between steps 1 and 3. The following table explains why each alternative mechanism fails to load the keyring within this window:

Mechanism	Reason for failure
INSTALL COMPONENT	The statement runs as SQL and cannot execute until step 4. The registration record lives in mysql.component, an InnoDB table that the server reads only after InnoDB initializes. The system tablespace cannot decrypt without the keyring, which creates a circular dependency. Crash recovery also runs before the SQL layer, so the encrypted redo log must remain readable without SQL.
--early-plugin-load	The flag applies to legacy keyring plugins, not components. Plugins and components load through separate subsystems. The flag cannot locate component entry points.

A component registered through INSTALL COMPONENT on a running server does not persist across restarts. On the next restart, InnoDB cannot unwrap tablespace keys because no manifest file exists on disk. A missing or malformed mysqld.my therefore prevents startup for any instance with encrypted tablespaces.

Install a keyring component

To install a keyring component:

1. Stop the mysqld process.

2. Create the manifest file at the chosen location. Use one of the examples in Manifest examples as a template.

3. Create the configuration file in the same directory as the manifest that declares the component. The name of the configuration file matches the component name with a .cnf extension.

4. Populate the configuration file with parameters for the chosen component. The required parameters depend on the component.

5. Set the file ownership of the manifest file and the configuration file to the mysql user.

6. Restrict read access on the configuration file to the mysql user. The configuration file may contain credentials.

7. Start the mysqld process.

Verify the installation

Connect to the server and run the following query:

SELECT * FROM performance_schema.keyring_component_status;

The query returns one row per status field. The Component_status field reports Active when the component loaded. The Component_status field reports Disabled when the component failed to load. Inspect the server error log to identify the cause of any failure.

Operate the keyring

Rotate the master key

The InnoDB master key wraps the tablespace keys that protect data on disk. Rotate the master key on a scheduled cadence. Scheduled rotation limits the volume of data wrapped by any single master key. See Data at Rest Encryption for the role of the master key.

Run the following statement to rotate the master key:

ALTER INSTANCE ROTATE INNODB MASTER KEY;

The statement generates a master key and stores the key in the keyring. The server then wraps subsequent tablespace keys with the stored key.

The rotation operation is fast. The server does not re-encrypt the tablespace data.

Earlier master keys must remain in the keyring. Deleting an earlier master key prevents the server from reading data that was wrapped with that key.

For required privileges and the full rotation procedure, see Rotate the master encryption key.

Monitor the keyring

Use the query in Verify the installation to inspect the keyring at runtime. Configure alerts on Component_status transitions to Disabled. Watch the server error log for keyring-related errors. The server writes manifest parse errors, configuration parse errors, and backend connection errors to the error log.

Back up and restore

A backup of an encrypted tablespace requires keyring access on the destination host. The destination host must read the same key material that encrypted the backup.

The following table summarizes the keyring requirement for each backend:

Backend	Backup requirement
component_keyring_file	Copy the keyring file alongside the data backup. The destination host must read the same key material.
component_keyring_vault	Configure the destination host to authenticate with the same Vault server and access the same secret_mount_point.
component_keyring_kmip	Configure the destination host to authenticate with the same KMIP server and access the same key namespace.
component_keyring_kms	Configure the destination host with credentials and permissions for the same cloud KMS keys.

Test a restore on a separate host before relying on the backup. A restore that runs on the original host can succeed even when the keyring configuration is incorrect.

Replace or remove a keyring component

To replace a keyring component:

1. Stop the mysqld process.

2. Edit the manifest file to reference the replacement component.

3. Create the configuration file for the replacement component.

4. Start the mysqld process.

To remove the keyring:

1. Confirm that no encrypted tablespaces exist on the server. A server with encrypted tablespaces cannot start without a keyring.

2. Stop the mysqld process.

3. Delete the manifest file.

4. Start the mysqld process.

Warning

Configure exactly one keyring per server instance. Percona Server does not support multiple keyring plugins, multiple keyring components, or any combination of plugin and component. Such configurations risk data loss.

Manifest file

The manifest tells the server to load component_percona_keyring_encrypted_file at startup. Create a file named mysqld.my in JSON format.

The server reads a global manifest from the directory that contains the mysqld binary. The path depends on your install method. Package installs on Linux often use /usr/sbin/mysqld.my. Tarball installs, containers, and custom builds may use another directory. Confirm the mysqld binary location before you create the manifest. You can place a local manifest in the data directory if multiple instances on one host need different keyring components.

Global manifest onlyGlobal and local manifests

{
  "read_local_manifest": false,
  "components": "file://component_percona_keyring_encrypted_file"
}

Global manifest in the directory that contains the mysqld binary:

{
  "read_local_manifest": true
}

Local manifest in the data directory:

{
  "components": "file://component_percona_keyring_encrypted_file"
}

Restart the server after you create or change a manifest.

Configuration file

The component reads settings from a JSON configuration file named component_percona_keyring_encrypted_file.cnf. The global configuration file is in the plugin directory by default. Confirm the path with the following statement:

SELECT @@plugin_dir;

Typical paths:

• /usr/lib64/mysql/plugin on RHEL-style systems

• /usr/lib/mysql/plugin on Debian and Ubuntu

You can place a local configuration file in the data directory when you set read_local_config in the global file.

The component_percona_keyring_encrypted_file.cnf file supports the following options. Option order in the JSON file does not matter. Place read_local_config only in the global configuration file in the plugin directory. Place path, read_only, and password or password_file in the global file or in the local file in the data directory, depending on read_local_config.

• password: Password for encryption and decryption of the keyring file. Specify password or password_file, not both. The password must not be empty.

• password_file: Path to a file that contains the password. Specify password_file or password, not both. Use this option to keep secrets out of the component configuration file. See File permissions.

• path: Full path to the keyring data file. The component creates this file on first use if the file does not exist. The directory must exist. Use a dedicated directory with restricted permissions. Do not use the data directory. See File permissions.

• read_local_config [optional]: Use this option only in the global configuration file. The option controls whether the component reads configuration from a local file in the data directory. Allowed values are true or false. If you omit this option, the component uses only the global configuration file.

  If the global file includes read_local_config and other items, the component checks read_local_config first:

  • false: The component uses the other items in the global file. The component ignores the local configuration file.

  • true: The component ignores the other items in the global file. The component reads the local configuration file.

• read_only: When true, the keyring rejects runtime changes. The keyring does not accept new keys or key removal. When false, the keyring accepts key changes. This option is mandatory.

Inline passwordPassword file

{
  "path": "/var/lib/mysql-keyring/component_percona_keyring_encrypted_file",
  "read_only": false,
  "password": "your-strong-password"
}

{
  "path": "/var/lib/mysql-keyring/component_percona_keyring_encrypted_file",
  "read_only": false,
  "password_file": "/var/lib/mysql-keyring/keyring.password"
}

Protect the keyring file and password

You need the encrypted keyring file at path and the correct password to access keys. See File permissions. Include the keyring file, password, and password file in backup and restore procedures.

Encrypted tablespaces, redo logs, and undo logs become unrecoverable if the keyring file is lost, corrupted, or opened with the wrong password. Do not delete or edit the keyring file manually to rotate keys. Use Rotate the master encryption key to rotate keys.

File permissions

The MySQL server user needs read access to the manifest, configuration file, and password file. The user needs read and write access to the keyring directory. Set ownership and permissions before you restart the server.

ManifestConfiguration fileKeyring directoryPassword file

sudo chown root:root /usr/sbin/mysqld.my
sudo chmod 644 /usr/sbin/mysqld.my

Adjust the path if your manifest is not in /usr/sbin.

cd /usr/lib64/mysql/plugin
sudo chown root:root component_percona_keyring_encrypted_file.cnf
sudo chmod 640 component_percona_keyring_encrypted_file.cnf

Adjust the path for your @@plugin_dir value. If you use inline password, use mode 640 or tighter on the configuration file.

The component creates the keyring data file at path on first use. Place path in a directory owned by the MySQL user with mode 750:

sudo chown mysql:mysql /var/lib/mysql-keyring
sudo chmod 750 /var/lib/mysql-keyring

When you set password_file, the MySQL server user must be able to read the file:

sudo chown mysql:mysql /var/lib/mysql-keyring/keyring.password
sudo chmod 600 /var/lib/mysql-keyring/keyring.password

On-disk format

The keyring payload is JSON. The file on disk is encrypted. Each write uses the following steps:

• PBKDF2-HMAC-SHA256 derives a 256-bit AES key from the password

• The component generates a random salt and initialization vector (IV)

• AES encrypts the JSON payload

The file starts with a version 1 header:

[version:1 byte][salt:32 bytes][iterations:4 bytes, big-endian][iv:16 bytes][ciphertext]

The default PBKDF2 iteration count is 600000. During writes, the component can create a .backup file next to the keyring data file for rollback.

Verify the component is loaded

Restart the server. Run the following statement to confirm that the keyring is active:

SELECT * FROM performance_schema.keyring_component_status;

If the component loaded successfully, the result includes the following values:

STATUS_KEY	Expected value
Component_name	component_percona_keyring_encrypted_file
Component_status	Active
Data_file	The path value from the configuration file
Read_only	Yes or No, matching the read_only setting
Password	<SET> with inline password; <NONE> otherwise
Password_file	File path with password_file; <NONE> otherwise

Example output:

+---------------------+---------------------------------------------------------------+
| STATUS_KEY          | STATUS_VALUE                                                  |
+---------------------+---------------------------------------------------------------+
| Component_name      | component_percona_keyring_encrypted_file                      |
| Author              | Percona                                                       |
| Component_status    | Active                                                        |
| Data_file           | /var/lib/mysql-keyring/component_percona_keyring_encrypted_file |
| Read_only           | No                                                            |
| Password            | <SET>                                                         |
| Password_file       | <NONE>                                                        |
+---------------------+---------------------------------------------------------------+

The Active status means the keyring is ready. The Active status does not mean data is encrypted. Enable encryption separately for tables, tablespaces, and logs. See Data at Rest Encryption.

If startup fails, check the error log with SELECT @@log_error;. Common causes:

• Missing or empty password

• Both password and password_file are set

• The MySQL server user cannot read the password file

• JSON syntax errors in the manifest or configuration file

• Wrong password for an existing keyring file

Reload the keyring configuration

You can reload the keyring after you change the component configuration file. You do not need a full server restart. Run the following statement:

ALTER INSTANCE RELOAD KEYRING;

Reload succeeds when the updated configuration is valid and the password decrypts the existing keyring file. Reload fails when the password is wrong. After a failed reload, the component can report Disabled in keyring_component_status.

Use the keyring with encryption

You can enable transparent data encryption (TDE) when component_percona_keyring_encrypted_file is active. TDE applies to the following objects:

• Individual tables and schema defaults: Encrypt file-per-table tablespace and Encrypt schema or general tablespace

• System tablespace: Encrypt system tablespace

• Redo and undo logs: Log encryption

• Binary and relay logs: Encrypt binary log files and relay log files

See Verify encryption to confirm encryption settings.

Migrate keyring data

The mysql_migrate_keyring utility copies keys between component_percona_keyring_encrypted_file and component_keyring_file. Both components need valid configuration files in the configuration directory that you pass to the utility. See Use the keyring file component for component_keyring_file details.

Follow these steps:

1. Stop the server.

2. Create configuration files for the source and destination keyring components.

3. Run mysql_migrate_keyring.

4. Update the manifest to load the destination component.

5. Start the server.

6. Verify keys and encrypted data.

The following example migrates from the encrypted Percona keyring to the unencrypted file keyring:

mysql_migrate_keyring \
  --component-dir=/usr/lib64/mysql/plugin \
  --source-keyring=component_percona_keyring_encrypted_file \
  --source-keyring-configuration-dir=/var/lib/mysql \
  --destination-keyring=component_keyring_file \
  --destination-keyring-configuration-dir=/var/lib/mysql

To migrate in the other direction, swap the --source-keyring and --destination-keyring values. The destination encrypted keyring configuration must include path, read_only, and password or password_file. Keep the server stopped during migration. Update mysqld.my to reference the destination component before you restart.

Operational notes

These notes apply after you load the component and use it for data at rest encryption. They cover backups, instance moves, clusters, key rotation, and compliance.

• Backups: Include the encrypted keyring file, password, and encrypted data in the same backup plan. Restore fails for encrypted tablespaces or logs without the keyring file and password.

• Cloning and migration: Copy the keyring file when you move an instance to new hardware. Use the same password in the component configuration on the new host before you start the server.

• Percona XtraDB Cluster (PXC): The keyring file is not replicated. Copy the keyring file from the bootstrap node to other nodes. Each node must use the same password in the component configuration.

• Master key rotation: Run ALTER INSTANCE ROTATE INNODB MASTER KEY to rotate the InnoDB master key. See Rotate the master encryption key.

• Compliance: A password-protected local keyring file protects keys at rest on the host. A local keyring file is not a substitute for a dedicated key management system or a hardware security module (HSM) when regulations require one.

Uninstall the component

Follow these steps to stop use of the encrypted file keyring:

1. Remove or rename the manifest entry for file://component_percona_keyring_encrypted_file in mysqld.my.

2. Remove or rename component_percona_keyring_encrypted_file.cnf.

3. Restart the server.

Do not delete the keyring data file if encrypted data exists on the instance. You need the keyring data file and the correct password to decrypt encrypted tablespaces and logs.

See also

Keyring components overview

Use the keyring file component

Get Started with component keyring

Data at Rest Encryption

Upgrade components

Rotate the master encryption key