Use the keyring vault component¶

The keyring_vault component extends the server capabilities and provides an interface for the database with a HashiCorp Vault server to store key and secure encryption keys.

The component must be installed with a manifest. A keyring component is not loaded with the --early-plugin-load option on the server. The server uses a manifest and the component consults its configuration file during initialization. You should only load a keyring component with a manifest file. Do not use the INSTALL_COMPONENT statement, which loads the keyring components too late in the startup sequence of the server. For example, InnoDB requires the component, but because the components are registered in the mysql.component table, this table is loaded after InnoDB initialization.

You should create a global manifest file named mysqld.my in the installation directory and, optionally, create a local manifest file, also named mysqld.my in a data directory.

To install a keyring component, do the following:

Write a manifest in a valid JSON format
Write a configuration file

A manifest file indicates which component to load. If the manifest file does not exist, the server does not load the component associated with that file. During startup, the server reads the global manifest file from the installation directory. The global manifest file can contain the required information or point to a local manifest file located in the data directory. If you have multiple server instances that use different keyring components use a local manifest file in each data directory to load the correct keyring component for that instance.

Warning

Enable only one keyring plugin or one keyring component at a time for each server instance. Enabling multiple keyring plugins or keyring components or mixing keyring plugins or keyring components is not supported and may result in data loss.

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

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

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_vault"
}

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

The component communicates with the Hashicorp Vault server. Prepare the certificate and key files for a secure HTTPS connection to the server. You must have an organizational Certificate Authority (CA), a private vault key, and certificate for the Hashicorp Vault server instance.

You can use OpenSL to generate these files or use existing files. The key files contain sensitive information. Store these key files and the password used to create each key in a secure location.

You can use the Hashicorp Vault to build your own CA, if needed, and then create a Hashicorp Vault server certificate.

The component_keyring_vault.cnf file contains the following information:

read_local_config [optional] - this option can be used only in the global configuration file. This option indicates whether the component should read configuration information from the local configuration file. The allowed values are true or false. If you do not use this option, the component uses only the global configuration file.

If you use the read_local_config option in the global configuration file along with other items, the component checks the read_local_config item value first:

false - the component processes other items in the global configuration file and ignores the local configuration file.

true - the component ignores other items in the global configuration file and attempts to read the local configuration file.
timeout - the duration in seconds for the Vault server connection timeout. The default value is 15. The allowed range is from 0 to 86400. The timeout can be also disabled to wait an infinite amount of time by setting this variable to 0.
vault_url - the Vault server address.
secret_mount_point - the mount point name where the keyring_vault stores the keys.
token - a token generated by the Vault server.
secret_mount_point_version [optional] - the KV Secrets Engine version (kv or kv-v2) used. The allowed values are AUTO, 1, and 2. The default value is AUTO.
vault_ca [optional] - if the machine does not trust the Vault’s CA certificate, this variable points to the CA certificate used to sign the Vault’s certificates.

Example of a configuration file in JSON format

{
 "timeout": 15,
 "vault_url": "https://vault.public.com:8202",
 "secret_mount_point": "secret",
 "secret_mount_point_version": "AUTO",
 "token": "{randomly-generated-alphanumeric-string}",
 "vault_ca": "/data/keyring_vault_confs/vault_ca.crt"
}

Warning

Each secret_mount_point must be used by only one server. The behavior is unpredictable if multiple servers use the same secret_mount_point.

The first time a key is fetched from a keyring, the keyring_vault communicates with the Vault server to retrieve the key type and data.

secret_mount_point_version information¶

The secret_mount_point_version can be either a 1, 2, AUTO, or the secret_mount_point_version parameter is not listed in the configuration file.

Value	Description
1	Works with `KV Secrets Engine - Version 1 (kv)`. When forming key operation URLs, the `secret_mount_point` is always used without any transformations. For example, to return a key named `skey`, the URL is /v1//skey
2	Works with `KV Secrets Engine - Version 2 (kv)` The initialization logic splits the `secret_mount_point` parameter into two parts: The `mount_point_path` - the mount path under which the Vault Server secret was created The `directory_path` - a virtual directory suffix that can be used to create virtual namespaces with the same real mount point For example, both the `mount_point_path` and the `directory_path` are needed to form key access URLs: /v1/<mount_point_path/data//skey
AUTO	An autodetection mechanism probes and determines if the secrets engine version is `kv` or `kv-v2` and based on the outcome will either use the `secret_mount_point` as is, or split the `secret_mount_point` into two parts.
Not listed	If the `secret_mount_point_version` is not listed in the configuration file, the behavior is the same as `AUTO`.

If you set the secret_mount_point_version to 2 but the path pointed by secret_mount_point is based on KV Secrets Engine - Version 1 (kv), an error is reported, and the component fails to initialize.

If you set the secret_mount_point_version to 1 but the path pointed by secret_mount_point is based on KV Secrets Engine - Version 2 (kv-v2), the component initialization succeeds but any MySQL keyring-related operations fail.

Upgrade from Vault Secrets Engine Version 1 to Version 2¶

You can upgrade from the Vault Secrets Engine Version 1 to Version 2.

Use either of the following methods:

Set the secret_mount_point_version to AUTO or the variable is not set in the keyring_vault component configuration files in all Percona Servers. The AUTO value ensures the autodetection mechanism is invoked during the component initialization.
Set the secret_mount_point_version to 2 to ensure that components do not initialize unless the kv to kv-v2 upgrade completes.

Note

The keyring_vault component that works with kv-v2 secret engines does not use the built-in key versioning capabilities. The keyring key versions are encoded into key names.

Get expert help¶

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services.

Community Forum Get a Percona Expert

Last update: 2024-10-30