You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Use the Key Management Interoperability Protocol (KMIP)
2
2
3
-
Percona Server for MySQL supports the [OASIS Key Management Interoperability Protocol (KMIP) :octicons-link-external-16:](https://docs.oasis-open.org/kmip/kmip-spec/v2.0/os/kmip-spec-v2.0-os.html). This implementation was tested with:
4
-
-[PyKMIP server :octicons-link-external-16:](https://pykmip.readthedocs.io/en/latest/server.html)
-[Fortanix Data Security Manager :octicons-link-external-16:](https://www.fortanix.com/products/data-security-manager)
3
+
Percona Server for MySQL supports the [OASIS Key Management Interoperability Protocol (KMIP) :octicons-link-external-16:](https://docs.oasis-open.org/kmip/kmip-spec/v2.0/os/kmip-spec-v2.0-os.html). Percona has validated the KMIP implementation against the following servers:
8
4
9
-
KMIP enables communication between key management systems and the database server. The protocol can do the following:
5
+
*[PyKMIP server :octicons-link-external-16:](https://pykmip.readthedocs.io/en/latest/server.html)
*[Fortanix Data Security Manager :octicons-link-external-16:](https://www.fortanix.com/products/data-security-manager)
12
+
13
+
KMIP enables communication between key management systems and the database server. The protocol provides the following capabilities:
14
+
15
+
* Streamlined encryption key management
16
+
17
+
* Elimination of redundant key management processes
14
18
15
19
## Component installation
16
20
17
21
--8<--- "keyring-components-installation.md"
18
22
19
23
For more information, see [Installing and Uninstalling Components :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/component-loading.html).
20
24
21
-
The following is an example of a global manifest file that does not use local manifests:
25
+
The following example shows a global manifest file that does not use local manifests:
22
26
23
27
```json
24
28
{
@@ -27,23 +31,23 @@ The following is an example of a global manifest file that does not use local ma
27
31
}
28
32
```
29
33
30
-
The following is an example of a global manifest file that points to a local manifest file:
34
+
The following example shows a global manifest file that references a local manifest file:
31
35
32
36
```json
33
37
{
34
38
"read_local_manifest": true
35
39
}
36
40
```
37
41
38
-
The following is an example of a local manifest file:
42
+
The following example shows a local manifest file:
39
43
40
44
```json
41
45
{
42
46
"components": "file://component_keyring_kmip"
43
47
}
44
48
```
45
49
46
-
The configuration settings are either in a global configuration file or a local configuration file. The settings are the same.
50
+
Both global and local configuration files use the same settings.
47
51
48
52
??? example "Example of a configuration file in JSON format"
49
53
@@ -53,8 +57,58 @@ The configuration settings are either in a global configuration file or a local
53
57
"server_port": "5696",
54
58
"client_ca": "client_certificate.pem",
55
59
"client_key": "client_key.pem",
56
-
"server_ca": "root_certificate.pem"
60
+
"server_ca": "root_certificate.pem",
61
+
"object_group": "",
62
+
"kmip_timeout_ms": 5000,
63
+
"tls_peer_verification": false,
64
+
"tls_hostname_verification": false
57
65
}
58
66
```
59
67
68
+
### Configuration options
69
+
70
+
The configuration file for the KMIP keyring supports the following options:
71
+
72
+
| Option | Type | Default | Description |
73
+
|---|---|---|---|
74
+
|`server_addr`| string | Required | Hostname or IP address of the KMIP server |
75
+
|`server_port`| string | Required | TCP port of the KMIP server, for example `"5696"`|
76
+
|`client_ca`| string | Required | Path to the client certificate that the client presents to the KMIP server, in PEM (Privacy-Enhanced Mail) format |
77
+
|`client_key`| string | Required | Path to the client private key that matches `client_ca`, in PEM format |
78
+
|`server_ca`| string | Required | Path to the CA (certificate authority) certificate that verifies the KMIP server, in PEM format |
79
+
|`object_group`| string |`""`| KMIP object group for registering and enumerating objects; empty value disables grouping |
80
+
|`kmip_timeout_ms`| integer |`5000`| KMIP connection timeout in milliseconds |
81
+
|`tls_peer_verification`| boolean |`false`| When `true`, verifies the KMIP server TLS (Transport Layer Security) certificate against `server_ca`|
82
+
|`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 |
83
+
84
+
#### TLS verification
85
+
86
+
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.
87
+
88
+
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.
89
+
90
+
### Requirements for KMIP object states
91
+
92
+
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.
93
+
94
+
!!! important
95
+
96
+
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.
97
+
98
+
### AES key size restriction
99
+
100
+
The KMIP keyring backend accepts only the standard AES key sizes:
101
+
102
+
| AES key size | Length in bytes |
103
+
|---|---|
104
+
| 128 bits | 16 |
105
+
| 192 bits | 24 |
106
+
| 256 bits | 32 |
107
+
108
+
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.
109
+
110
+
!!! important
111
+
112
+
Review any scripts or tooling that use non-standard AES key sizes before you upgrade.
113
+
60
114
For more information, see [Keyring Component installation :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/keyring-component-installation.html).
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.
2
+
Install a keyring component through a manifest file. During startup, the server reads the manifest. Each component reads a corresponding configuration file during initialization.
3
3
4
-
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.
4
+
Do not load keyring components with either of the following methods:
5
5
6
-
To install a keyring component, do the following:
6
+
| Method | Why it fails |
7
+
|---|---|
8
+
|`--early-plugin-load` option | Loads plugins only, not components |
9
+
|`INSTALL COMPONENT` statement | Registers components in the `mysql.component` table, which the server loads after `InnoDB` initialization |
7
10
8
-
1. Write a manifest in a valid JSON format
11
+
Components that `InnoDB` requires at startup must load earlier.
12
+
13
+
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.
14
+
15
+
To install a keyring component, complete the following steps:
16
+
17
+
1. Write a manifest in valid JSON format
9
18
10
19
2. Write a configuration file
11
20
12
-
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.
21
+
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.
22
+
23
+
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.
13
24
14
25
!!! warning
15
26
16
-
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.
27
+
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.
0 commit comments