Use the Key Management Interoperability Protocol (KMIP)

Percona Server for MySQL supports the OASIS Key Management Interoperability Protocol (KMIP) . This implementation was tested with: - PyKMIP server - HashiCorp Vault Enterprise KMIP Secrets Engine - Thales CipherTrust Manager - Fortanix Data Security Manager

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

• Streamline encryption key management

• Eliminate redundant key management processes

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 is an example of a global manifest file that does not use local manifests:

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

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

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

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

For more information, see Keyring Component installation .