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.

Install a keyring component through a manifest file. During startup, the server reads the manifest. Each component reads a corresponding configuration file during initialization.

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.

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.

To install a keyring component, complete the following steps:

Write a manifest in valid JSON format
Write a configuration file

A manifest file declares which component to load. The server skips any component whose manifest file does not exist. During startup, the server reads the global manifest file from the installation directory. The global manifest file either contains the required information or references a local manifest file in the data directory.

Use a local manifest file in each data directory when you run multiple server instances with different keyring components. Each instance then loads the correct keyring component.

Warning

Enable only one keyring plugin or keyring component per server instance. Percona Server does not support multiple or mixed keyring implementations. Unsupported configurations can cause 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 OpenSSL 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.