Skip to content
Percona Software for MySQL Documentation

Rate this page
☆ ☆ ☆ ☆ ☆
Thanks for your feedback
Thank you! The feedback has been submitted.

For help, click the link below to get free database assistance or contact our experts for personalized support.

Get help from Percona

Use the Amazon Key Management Service (AWS KMS)

Percona Server for MySQL supports the Amazon Key Management Service (AWS KMS) . Percona Server generates the keyring keys. Amazon Web Services (AWS) encrypts the keyring data.

The AWS KMS lets you create and manage cryptographic keys across AWS services. For more information, see the AWS Key Management Service Documentation .

To use the AWS KMS component, do the following:

  • Have an AWS user account. This account has an access key and a secret key.

  • Create a KMS key ID. The KMS key can then be referenced in the configuration either by its ID, alias (the key can have any number of aliases), or ARN.

Component installation

Percona Server relies on a keyring to safeguard the master keys that encrypt data at rest. A manifest file loads the keyring component, which reads a separate configuration file during initialization. Avoid --early-plugin-load and INSTALL COMPONENT: neither mechanism can load a keyring early enough in startup.

Why the manifest is the only supported load path

The keyring must be live before InnoDB opens an encrypted page, which rules out any mechanism that depends on a running SQL layer. A typical startup proceeds in this order:

  1. mysqld parses startup configuration and reads the manifest file next to the binary.

  2. The server loads components named in the manifest.

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

  4. The SQL layer accepts connections.

The keyring must be ready between steps 1 and 3. Both alternative mechanisms miss that window:

  • INSTALL COMPONENT runs as SQL, so the statement cannot execute until step 4. The registration lives in mysql.component, an InnoDB table the server reads only after InnoDB initializes — a circular dependency when the system tablespace is encrypted. Crash recovery also runs before SQL, so an encrypted redo log must be readable without any SQL layer.

  • --early-plugin-load applies to legacy keyring plugins, not components. Plugins and components load through separate subsystems; the flag cannot locate component entry points. The manifest is the only early-load channel for components.

One practical consequence: a component registered through INSTALL COMPONENT on a running server disappears on the next restart, so InnoDB fails to unwrap tablespace keys without a manifest file on disk. A missing or malformed mysqld.my is therefore a startup failure for any instance with encrypted tablespaces.

Place a global manifest named mysqld.my in the server installation directory. For per-instance overrides, add a local manifest — also named mysqld.my — in the data directory.

To install a keyring component:

  1. Write the manifest file in valid JSON.

  2. Write the component’s configuration file in valid JSON.

The manifest names the component to load. Without a matching manifest file, the server quietly skips the component. On startup, the server reads the global manifest from the installation directory; the global manifest either holds the component entries directly or delegates to a local manifest in the data directory. When instances on the same host require different keyring components, place a local manifest in each data directory so every instance loads the correct component.

Warning

Run exactly one keyring per server instance. Percona Server does not support multiple keyring plugins, multiple keyring components, or any mix of plugin and component — such configurations risk data loss.

For more information, see Installing and Uninstalling Components .

The following example is a global manifest file that does not use local manifests:

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

The following is an example of a global manifest file that points to a local manifest file:

{
 "read_local_manifest": true
}

The following is an example of a local manifest file:

{
 "components": "file://component_keyring_kms"
}

The configuration settings are either in a global configuration file or a local configuration file. The settings are the same.

The KMS configuration file has the following options:

  • read_local_config

  • path - the location of the JSON keyring database file.

  • read_only - if true, the keyring cannot be modified.

  • kms_key - the identifier of an AWS KMS master key. The user must create this key before creating the manifest file. The identifier can be one of the following:

    • UUID

    • Alias

    • ARN

For more information, see Finding the key ID and key ARN .

  • region - the AWS where the KMS is stored. Any HTTP request connect to this region.

  • auth_key - an AWS user authentication key. The user must have access to the KMS key.

  • secret_access_key - the secret key (API “password”) for the AWS user.

Note

The configuration file contains authentication information. Only the MySQL process should be able to read this file.

Example of a configuration file in JSON format 
{
 "read_local_config": "true/false",
 "path": "/usr/local/mysql/keyring-mysql/aws-keyring-data",
 "region": "eu-central-1",
 "kms_key": "UUID, alias or ARN as displayed by the KMS console",
 "auth_key": "AWS user key",
 "secret_access_key": "AWS user secret key"
}

For more information, see Keyring Component installation .