Use the Key Management Interoperability Protocol (KMIP)¶

Percona Server for MySQL supports the OASIS Key Management Interoperability Protocol (KMIP) . Percona has validated the KMIP implementation against the following servers:

KMIP enables communication between key management systems and the database server. The protocol provides the following capabilities:

Streamlined encryption key management
Elimination of redundant key management processes

Component installation¶

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.

For more information, see Installing and Uninstalling Components .

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

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

The following example shows a global manifest file that references a local manifest file:

{
 "read_local_manifest": true
}

The following example shows a local manifest file:

{
 "components": "file://component_keyring_kmip"
}

Both global and local configuration files use the same settings.

Example of a configuration file in JSON format

{
 "server_addr": "127.0.0.1",
 "server_port": "5696",
 "client_ca": "client_certificate.pem",
 "client_key": "client_key.pem",
 "server_ca": "root_certificate.pem",
 "object_group": "",
 "kmip_timeout_ms": 5000,
 "tls_peer_verification": false,
 "tls_hostname_verification": false
}

Configuration options¶

The configuration file for the KMIP keyring supports the following options:

Option	Type	Default	Description
`server_addr`	string	Required	Hostname or IP address of the KMIP server
`server_port`	string	Required	TCP port of the KMIP server, for example `"5696"`
`client_ca`	string	Required	Path to the client certificate that the client presents to the KMIP server, in PEM (Privacy-Enhanced Mail) format
`client_key`	string	Required	Path to the client private key that matches `client_ca`, in PEM format
`server_ca`	string	Required	Path to the CA (certificate authority) certificate that verifies the KMIP server, in PEM format
`object_group`	string	`""`	KMIP object group for registering and enumerating objects; empty value disables grouping
`kmip_timeout_ms`	integer	`5000`	KMIP connection timeout in milliseconds
`tls_peer_verification`	boolean	`false`	When `true`, verifies the KMIP server TLS (Transport Layer Security) certificate against `server_ca`
`tls_hostname_verification`	boolean	`false`	When `true`, verifies that `server_addr` matches the Subject Alternative Name (SAN) or Common Name (CN) in the KMIP server certificate

TLS verification¶

Both tls_peer_verification and tls_hostname_verification default to false for backward compatibility. Enable both options in production deployments. The server then rejects KMIP endpoints that present an untrusted or mismatched certificate.

To use peer verification, set server_ca to reference the certificate authority that signed the KMIP server certificate. To use hostname verification, set server_addr to a value that matches the SAN or CN in the KMIP server certificate.

Requirements for KMIP object states¶

The KMIP keyring backend loads only KMIP objects in the ACTIVE state. Loaded objects include symmetric keys and secret data. The backend ignores objects in the PRE_ACTIVE, DEACTIVATED, COMPROMISED, or DESTROYED state. The backend activates each key or secret automatically when the backend registers the object.

Important

Activate any PRE_ACTIVE keys on the KMIP server before you start Percona Server for MySQL. Otherwise, Percona Server for MySQL cannot load those keys.

Use the KMIP Activate operation through the management interface of your KMIP server. Possible interfaces include a web console, a command-line tool, or a KMIP client library. For exact steps, see the documentation of your KMIP server.

AES key size restriction¶

The KMIP keyring backend accepts only the standard AES key sizes:

AES key size	Length in bytes
128 bits	16
192 bits	24
256 bits	32

An attempt to generate or store an AES key of any other length fails with a keyring service error. The keyring_udf plugin returns this error when a caller requests a non-standard key size.

Important

Review any scripts or tooling that use non-standard AES key sizes before you upgrade.

For more information, see Keyring Component installation .