diff --git a/docs/feature-comparison.md b/docs/feature-comparison.md index fd0cf8f852b..1c7b5086996 100644 --- a/docs/feature-comparison.md +++ b/docs/feature-comparison.md @@ -77,6 +77,7 @@ compared to the standard *MySQL* database server: | Encryption Features | Percona Server for MySQL {{vers}} | MySQL {{vers}} | |---|---|---| | Storing Keyring in a File | Yes | Yes | +| [Storing Keyring in an Encrypted Local File](use-percona-keyring-encrypted-file.md) | Yes | Enterprise Only | | Storing Keyring in Hashicorp Vault | Yes | Enterprise Only | | Encrypt InnoDB Data | Yes | Yes | | Encrypt InnoDB Logs | Yes | Yes | diff --git a/docs/index-contents.md b/docs/index-contents.md index db63b460188..a5624171dbe 100644 --- a/docs/index-contents.md +++ b/docs/index-contents.md @@ -186,6 +186,7 @@ - [Upgrade to Percona Server for MySQL Pro](upgrade-pro.md) - [Upgrade procedures for {{vers}}](upgrade-procedures.md) - [Upgrading from plugins to components](upgrade-components.md) +- [Use the Percona encrypted keyring file component](use-percona-keyring-encrypted-file.md) - [Use an APT repository to install Percona Server for MySQL {{vers}}](apt-repo.md) - [Use Docker Compose and named volumes](docker-compose.md) - [Use Percona Monitoring and Management (PMM) Advisors](advisors.md) diff --git a/docs/keyring-components-plugins-overview.md b/docs/keyring-components-plugins-overview.md index 488976df543..4c66c61c6d5 100644 --- a/docs/keyring-components-plugins-overview.md +++ b/docs/keyring-components-plugins-overview.md @@ -12,6 +12,8 @@ Percona Server supports the following keyring components: [Use the keyring file component](use-keyring-file.md){.md-button} +[Use the Percona encrypted keyring file component](use-percona-keyring-encrypted-file.md){.md-button} + [Use the keyring vault component](use-keyring-vault-component.md){.md-button} [Use the Key Management Interoperability Protocol (KMIP)](using-kmip.md){.md-button} diff --git a/docs/use-keyring-file.md b/docs/use-keyring-file.md index 37fc2845538..097432ebc99 100644 --- a/docs/use-keyring-file.md +++ b/docs/use-keyring-file.md @@ -1,43 +1,180 @@ # Use the keyring file component -The `keyring_file` component is part of the component-based MySQL infrastructure which extends the server capabilities. +The `component_keyring_file` component stores encryption keys in a local file on the server filesystem. Percona Server for MySQL uses this component for [data at rest encryption](data-at-rest-encryption.md), including InnoDB tablespace encryption and encrypted redo and undo logs. Other server features that need a keyring, such as the audit log filter component, can also use it. + +For a password-protected encrypted keyring file, see [Use the Percona encrypted keyring file component](use-percona-keyring-encrypted-file.md) (`component_percona_keyring_encrypted_file`). + +In Percona Server for MySQL {{vers}}, the supported keyring model is component-based. The legacy `keyring_file` plugin is not available. !!! important - Percona Server for MySQL {{vers}} does not support the `keyring_file` plugin. + Percona Server for MySQL {{vers}} does not support the `keyring_file` plugin. Use `component_keyring_file` instead. + + Enable only one keyring at a time. Do not load legacy keyring plugins (such as `keyring_file` or `keyring_vault`) together with a keyring component. + + If you already have data encrypted with a legacy keyring plugin, plan a migration before switching to the component keyring. Keys and encrypted data from the old plugin are not readable by the new component without migration. See [Upgrade components](upgrade-components.md) and [Get Started with component keyring](quickstart-component-keyring.md). -See the MySQL documentation on the [component installation :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/keyring-component-installation.html) and on the [keyring_file component usage :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/keyring-file-component.html) for more information. +For a step-by-step setup walkthrough, see [Get Started with component keyring](quickstart-component-keyring.md). --8<--- "keyring-components-installation.md" -An example of a manifest and a configuration file is the following: +## Manifest file + +The manifest tells the server to load `component_keyring_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 also use a local manifest in the data directory when multiple instances on the same host need different keyring components. + +The following example is a global manifest file that does not use local manifests: -An example of `./bin/mysqld.my`: +```json +{ + "read_local_manifest": false, + "components": "file://component_keyring_file" +} +``` + +The following is an example of a global manifest file that points to a local manifest file: ```json { - "components": "file://component_keyring_file" + "read_local_manifest": true } ``` -An example of `/lib/plugin/component_keyring_file.cnf`: +The following is an example of a local manifest file: ```json { - "path": "/var/lib/mysql-keyring/keyring_file", "read_only": false + "components": "file://component_keyring_file" } ``` ---8<--- "keyring-components-verification.md" +When `read_local_manifest` is `true`, the global manifest contains only that setting. The server reads the component list from `mysqld.my` in the data directory. + +After you create or change a manifest, restart the server. Loading a keyring component from a manifest is not supported at runtime with `INSTALL COMPONENT`; InnoDB needs the keyring during startup. + +## Configuration file + +The component reads settings from a JSON configuration file named `component_keyring_file.cnf`. + +By default, the global configuration file is in the plugin directory. Confirm the path with: + +```sql +SELECT @@plugin_dir; +``` + +Typical locations are `/usr/lib64/mysql/plugin` on RHEL-style systems and `/usr/lib/mysql/plugin` on Debian and Ubuntu. + +You can also place a local configuration file in the data directory when `read_local_config` is enabled in the global file. This pattern is useful when several server instances share one installation but need separate keyring files. + +The configuration settings are either in a global configuration file or a local configuration file. + +The `component_keyring_file.cnf` file supports the following options: + +* `read_local_config` [optional] — use only in the global configuration file. Indicates whether the component should read 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. + + When `read_local_config` appears in the global file along with other items, the component evaluates it first: + + * `false` — the component uses the other items in the global file and ignores the local configuration file. + + * `true` — the component ignores the other items in the global file and reads the local configuration file instead. + +* `path` — the full path to the keyring data file. The component creates this file on first use if it does not exist. The directory must exist and be writable by the MySQL server user. Use a dedicated directory with restricted permissions, not the data directory itself. + +* `read_only` [optional] — when `true`, the keyring cannot be modified at runtime (no new keys and no key removal). The default is `false`. Set `read_only` to `true` on replicas or read-only nodes where keys should not change. + +??? example "Example of a configuration file in JSON format" + + ```json + { + "path": "/var/lib/mysql-keyring/component_keyring_file", + "read_only": false + } + ``` + +!!! warning "Protect the keyring data file" + + The file at `path` holds the keys that decrypt your data. Restrict filesystem access to the keyring directory and include the keyring file in your backup and restore procedures. + + If the keyring file is lost, corrupted, or replaced, encrypted tablespaces, redo logs, and undo logs that depend on those keys are **unrecoverable**. Do not delete or manually edit the keyring file to rotate keys. Use [Rotate the master encryption key](rotate-master-key.md) instead. + +## Verify the component is loaded + +After a restart, confirm that the keyring is active: + +```sql +SELECT * FROM performance_schema.keyring_component_status; +``` + +When the component loaded successfully, the result includes: + +| STATUS_KEY | Expected value | +|------------------|-----------------------------------------------------| +| Component_name | `component_keyring_file` | +| Component_status | `Active` | +| Data_file | The `path` value from your configuration file | +| Read_only | `Yes` or `No`, matching your `read_only` setting | + +Example: + +```text ++---------------------+-----------------------------------------------+ +| STATUS_KEY | STATUS_VALUE | ++---------------------+-----------------------------------------------+ +| Component_name | component_keyring_file | +| Component_status | Active | +| Data_file | /var/lib/mysql-keyring/component_keyring_file | +| Read_only | No | ++---------------------+-----------------------------------------------+ +``` + +An `Active` status means the keyring is ready. It does not mean your data is encrypted yet. Enable encryption separately for tables, tablespaces, and logs. See [Data at Rest Encryption](data-at-rest-encryption.md). + +If the server starts but the component is missing or inactive, check the error log (`SELECT @@log_error;`) for JSON syntax errors in the manifest or configuration file, missing component libraries in `@@plugin_dir`, or permission problems on the manifest, configuration, or keyring paths. + +## Use the keyring with encryption + +With `component_keyring_file` active, you can enable transparent data encryption (TDE) for: + +* Individual tables and schema defaults — see [Encrypt file-per-table tablespace](encrypt-file-per-table-tablespace.md) and [Encrypt schema or general tablespace](encrypt-tablespaces.md) +* The system tablespace — see [Encrypt system tablespace](encrypt-system-tablespace.md) +* Redo and undo logs — see [Log encryption](encrypt-logs.md) +* Binary and relay logs — see [Encrypt binary log files and relay log files](encrypt-binary-relay-log-files.md) + +To confirm encryption settings after you enable them, see [Verify encryption](verify-encryption.md). + +## Operational notes + +* **Backups** — back up the keyring file together with encrypted data. Restoring encrypted tablespaces or logs without the matching keyring file fails. + +* **Cloning and migration** — when you move an instance to new hardware or copy a datadir, copy the keyring file to the new host before starting the server with encrypted data. + +* **Percona XtraDB Cluster (PXC)** — the keyring file is not replicated. Copy the keyring file from the bootstrap node to other nodes before they start with encrypted data. + +* **Master key rotation** — use `ALTER INSTANCE ROTATE INNODB MASTER KEY` to rotate the InnoDB master key. See [Rotate the master encryption key](rotate-master-key.md). + +* **Permissions** — the MySQL server user needs read access to the manifest and configuration files and read/write access to the keyring directory. A typical layout is `root:root` with mode `644` on the manifest, `640` on the configuration file, and `750` on the keyring directory owned by the MySQL user. + +## Uninstall the component + +To stop using the file keyring: + +1. Remove or rename the manifest entry for `file://component_keyring_file` in `mysqld.my`. +2. Remove or rename `component_keyring_file.cnf`. +3. Restart the server. + +Do not delete the keyring data file if any data on the instance was encrypted with it. You need that file to decrypt existing encrypted tablespaces and logs. + +!!! admonition "See also" -## Related topics + [Keyring components overview](keyring-components-plugins-overview.md) -* [Keyring components overview](keyring-components-plugins-overview.md) + [Use the Percona encrypted keyring file component](use-percona-keyring-encrypted-file.md) -* [Use the keyring vault component](use-keyring-vault-component.md) + [Get Started with component keyring](quickstart-component-keyring.md) -* [Use the Key Management Interoperability Protocol (KMIP)](using-kmip.md) + [Data at Rest Encryption](data-at-rest-encryption.md) -* [Use the Amazon Key Management Service (AWS KMS)](using-amz-kms.md) + [Upgrade components](upgrade-components.md) -* [Data at rest encryption](data-at-rest-encryption.md) + [Rotate the master encryption key](rotate-master-key.md) diff --git a/docs/use-percona-keyring-encrypted-file.md b/docs/use-percona-keyring-encrypted-file.md new file mode 100644 index 00000000000..ec503fb062b --- /dev/null +++ b/docs/use-percona-keyring-encrypted-file.md @@ -0,0 +1,463 @@ +# 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](data-at-rest-encryption.md) the same way as other keyring components. + +The [Use the keyring file component](use-keyring-file.md) 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](upgrade-components.md) and [Migrate keyring data](#migrate-keyring-data). + +See [Get Started with component keyring](quickstart-component-keyring.md) for a walkthrough of the unencrypted file keyring. + +## Version changes + +Percona Server for MySQL {{vers}} includes `component_percona_keyring_encrypted_file` from release 8.4.11-11. + +## 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-keyring-vault-component.md) +* [Use AWS KMS](using-amz-kms.md) +* [Use KMIP](using-kmip.md) + +## Component installation + +--8<--- "keyring-components-installation.md" + +## 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 only" + + ```json + { + "read_local_manifest": false, + "components": "file://component_percona_keyring_encrypted_file" + } + ``` + +=== "Global and local manifests" + + Global manifest in the directory that contains the `mysqld` binary: + + ```json + { + "read_local_manifest": true + } + ``` + + Local manifest in the data directory: + + ```json + { + "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: + +```sql +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](#file-permissions). + +* `path`: Absolute path to the keyring data file. The component creates this file on first use if the file does not exist. The directory must exist. The path must not point to the MySQL data directory or to a location inside the data directory. Use a dedicated directory with restricted permissions. Relative paths are not supported. See [File permissions](#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 password" + + ```json + { + "path": "/var/lib/mysql-keyring/component_percona_keyring_encrypted_file", + "read_only": false, + "password": "your-strong-password" + } + ``` + +=== "Password file" + + ```json + { + "path": "/var/lib/mysql-keyring/component_percona_keyring_encrypted_file", + "read_only": false, + "password_file": "/var/lib/mysql-keyring/keyring.password" + } + ``` + +!!! warning "Protect the keyring file and password" + + You need the encrypted keyring file at `path` and the correct password to access keys. See [File permissions](#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](rotate-master-key.md) 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. + +=== "Manifest" + + ```bash + 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`. + +=== "Configuration file" + + ```bash + 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. + +=== "Keyring directory" + + The component creates the keyring data file at `path` on first use. Use an absolute path to a dedicated directory outside the MySQL data directory. The directory must exist and the MySQL user must have read and write access. + + For example: + + ```bash + sudo chown mysql:mysql /var/lib/mysql-keyring + sudo chmod 750 /var/lib/mysql-keyring + ``` + +=== "Password file" + + When you set `password_file`, the MySQL server user must be able to read the file: + + ```bash + 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: + +```text +[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: + +```sql +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 | `` with inline `password`; `` otherwise | +| Password_file | File path with `password_file`; `` otherwise | + +Example output: + +```text ++---------------------+---------------------------------------------------------------+ +| 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 | | +| Password_file | | ++---------------------+---------------------------------------------------------------+ +``` + +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](data-at-rest-encryption.md). + +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: + +```sql +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`. + +## Change the keyring password + +The password in the `component_percona_keyring_encrypted_file` configuration encrypts the keyring data file. Changing `password` or the contents of `password_file` does not re-encrypt an existing keyring file with the new password. + +To change the password, migrate the keys temporarily from `component_percona_keyring_encrypted_file` to the unencrypted `component_keyring_file`, configure `component_percona_keyring_encrypted_file` with the new password, and migrate the keys back to a new encrypted keyring file. + +!!! warning + + Stop the MySQL server before you start the migration and keep the server stopped until the migration is complete. + + `component_keyring_file` stores the intermediate keyring data in an unencrypted file. Protect the file from unauthorized access and remove it after you successfully migrate the keys back to `component_percona_keyring_encrypted_file`. + +1. Before you stop the server, check the directory where the keyring component libraries are installed: + + ```sql + SELECT @@plugin_dir; + ``` + + Use this directory as the value of `--component-dir` in the migration commands. + +2. Stop the MySQL server: + + ```bash + sudo systemctl stop mysql + ``` + +3. Configure `component_keyring_file` as the temporary destination for the first migration. + + The `mysql_migrate_keyring` utility must be able to load the configuration for both the source and destination keyring components. + + If the component uses a local configuration file, set `"read_local_config": true` in its global configuration file and place the local configuration file in the directory that you specify with `--source-keyring-configuration-dir` or `--destination-keyring-configuration-dir`. + + Configure `component_keyring_file` to use a temporary keyring data file that does not already exist. Use an absolute path outside the MySQL data directory. For example: + + ```json + { + "path": "/var/lib/mysql-keyring/keyring_file_plain", + "read_only": false + } + ``` + +4. Migrate the keys from `component_percona_keyring_encrypted_file` to `component_keyring_file`: + + ```bash + mysql_migrate_keyring \ + --component-dir= \ + --source-keyring=component_percona_keyring_encrypted_file \ + --source-keyring-configuration-dir= \ + --destination-keyring=component_keyring_file \ + --destination-keyring-configuration-dir= + ``` + + Replace: + + * `` with the directory that contains the keyring component libraries. + * `` with the directory that contains the local configuration for `component_percona_keyring_encrypted_file`. + * `` with the directory that contains the local configuration for `component_keyring_file`. + + Verify that the migration completes successfully before you continue. + +5. Update the `component_percona_keyring_encrypted_file` configuration with the new password. + + If you configure the password directly, replace the existing `password` value: + + ```json + { + "path": "/var/lib/mysql-keyring/component_percona_keyring_encrypted_file", + "read_only": false, + "password": "new-strong-password" + } + ``` + + If you use `password_file`, replace the password stored in the file specified by `password_file`. + + Keep the existing `path` value unless you also intend to change the location of the encrypted keyring data file. + +6. Move the existing encrypted keyring data file to a secure backup location. + + The `path` configured for `component_percona_keyring_encrypted_file` must not contain the old encrypted keyring file when you migrate the keys back. The second migration creates a new encrypted keyring file at this location. + + For example: + + ```bash + sudo mv \ + /var/lib/mysql-keyring/component_percona_keyring_encrypted_file \ + /secure/backup/location/component_percona_keyring_encrypted_file.old + ``` + + !!! important + + Verify that the migration to `component_keyring_file` completed successfully before you move the existing encrypted keyring file. + + Keep the original encrypted keyring file and the old password until you verify that the migration with the new password succeeded and that the server can access the encrypted data. + +7. Migrate the keys from the temporary `component_keyring_file` back to `component_percona_keyring_encrypted_file`: + + ```bash + mysql_migrate_keyring \ + --verbose \ + --component-dir= \ + --source-keyring=component_keyring_file \ + --source-keyring-configuration-dir= \ + --destination-keyring=component_percona_keyring_encrypted_file \ + --destination-keyring-configuration-dir= + ``` + + The migration reads the keys from the temporary unencrypted keyring and creates a new encrypted keyring data file at the `path` configured for `component_percona_keyring_encrypted_file`. The component uses the new `password` or `password_file` value to encrypt the file. + +8. Remove the temporary unencrypted keyring data file and clean up the temporary `component_keyring_file` configuration after the migration completes successfully. + + Remove the configuration file only if you created it for this migration. If you modified an existing `component_keyring_file` configuration, restore its previous settings instead. + + ```bash + sudo rm /var/lib/mysql-keyring/keyring_file_plain + sudo rm /component_keyring_file.cnf + ``` + +9. Start the MySQL server: + + ```bash + sudo systemctl start mysql + ``` + +10. Verify that `component_percona_keyring_encrypted_file` is active: + + ```sql + SELECT STATUS_KEY, STATUS_VALUE + FROM performance_schema.keyring_component_status + WHERE STATUS_KEY IN ('Component_name', 'Component_status'); + ``` + + Verify that `Component_name` is `component_percona_keyring_encrypted_file` and `Component_status` is `Active`. + + Verify that encrypted tables and other encrypted data that use keys from the keyring remain accessible. + +After you verify the new encrypted keyring and encrypted data, securely remove the backup of the old encrypted keyring file when you no longer need it. + +## 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](encrypt-file-per-table-tablespace.md) and [Encrypt schema or general tablespace](encrypt-tablespaces.md) +* System tablespace: [Encrypt system tablespace](encrypt-system-tablespace.md) +* Redo and undo logs: [Log encryption](encrypt-logs.md) +* Binary and relay logs: [Encrypt binary log files and relay log files](encrypt-binary-relay-log-files.md) + +See [Verify encryption](verify-encryption.md) 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](use-keyring-file.md) 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: + +```bash +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](rotate-master-key.md). + +* 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. + +!!! admonition "See also" + + [Keyring components overview](keyring-components-plugins-overview.md) + + [Use the keyring file component](use-keyring-file.md) + + [Get Started with component keyring](quickstart-component-keyring.md) + + [Data at Rest Encryption](data-at-rest-encryption.md) + + [Upgrade components](upgrade-components.md) + + [Rotate the master encryption key](rotate-master-key.md) diff --git a/mkdocs-base.yml b/mkdocs-base.yml index e88c427cfc3..f781ee4e348 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -380,6 +380,7 @@ nav: - keyring-components-plugins-overview.md - quickstart-component-keyring.md - use-keyring-file.md + - use-percona-keyring-encrypted-file.md - use-keyring-vault-component.md - maintain-vault-connection.md - using-kmip.md @@ -453,4 +454,3 @@ nav: - glossary.md - ai-docs.md - Topic Index: index-contents.md -# - Version Selector: "../" diff --git a/snippets/keyring-components-installation.md b/snippets/keyring-components-installation.md index cb0c5068258..93d2e3eba1c 100644 --- a/snippets/keyring-components-installation.md +++ b/snippets/keyring-components-installation.md @@ -1,27 +1,25 @@ -Install a keyring component through a manifest file. During startup, the server reads the manifest. Each component reads a corresponding configuration file during initialization. +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. -Do not load keyring components with either of the following methods: -| Method | Why it fails | -|---|---| -| `--early-plugin-load` option | Loads plugins only, not components | -| `INSTALL COMPONENT` statement | Registers components in the `mysql.component` table, which the server loads after `InnoDB` initialization | - -Components that `InnoDB` requires at startup must load earlier. +## Available keyring components -Create a global manifest file named `mysqld.my` in the installation directory. Optionally, create a local manifest file with the same name in a data directory. +Percona Server provides the following keyring components: -To install a keyring component, complete the following steps: +| 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 | -1. Write a manifest in valid JSON format +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` -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` extension. For example, `component_keyring_vault` reads `component_keyring_vault.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 -### Manifest fields - The manifest is a JavaScript Object Notation (JSON) object with the following fields: | Field | Type | Required | Description | @@ -123,7 +121,7 @@ The query returns one row per status field. The `Component_status` field reports ### 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 to limit the volume of data wrapped by any single 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](data-at-rest-encryption.md) for the role of the master key. Run the following statement to rotate the master key: