Skip to content

Commit 6cb76ad

Browse files
patrickbirchpatrickbirch
committed
PS-11074 [DOCS] - Update the KMIP information based on library update 8.4
 modified: docs/keyring-components-plugins-overview.md modified: docs/using-kmip.md
1 parent 506bc4d commit 6cb76ad

7 files changed

Lines changed: 171 additions & 38 deletions

‎docs/keyring-components-plugins-overview.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,6 @@ Percona Server supports the following keyring components:
1414

1515
[Use the keyring vault component](use-keyring-vault-component.md){.md-button}
1616

17-
[Use the Key Management Interoperability Protocol (KMIP)](using-amz-kms.md){.md-button}
17+
[Use the Key Management Interoperability Protocol (KMIP)](using-kmip.md){.md-button}
1818

19-
[Use the Amazon Key Management Service (AWS KMS)](using-kmip.md){.md-button}
19+
[Use the Amazon Key Management Service (AWS KMS)](using-amz-kms.md){.md-button}

‎docs/use-keyring-file.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,17 @@ An example of `/lib/plugin/component_keyring_file.cnf`:
2727
"path": "/var/lib/mysql-keyring/keyring_file", "read_only": false
2828
}
2929
```
30-
30+
31+
--8<--- "keyring-components-verification.md"
32+
33+
## Related topics
34+
35+
* [Keyring components overview](keyring-components-plugins-overview.md)
36+
37+
* [Use the keyring vault component](use-keyring-vault-component.md)
38+
39+
* [Use the Key Management Interoperability Protocol (KMIP)](using-kmip.md)
40+
41+
* [Use the Amazon Key Management Service (AWS KMS)](using-amz-kms.md)
42+
43+
* [Data at rest encryption](data-at-rest-encryption.md)

‎docs/use-keyring-vault-component.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -108,10 +108,22 @@ Use either of the following methods:
108108

109109
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.
110110

111+
--8<--- "keyring-components-verification.md"
112+
111113
!!! admonition "See also"
112114

113-
[Hashicorp Documentation: Installing Vault :octicons-link-external-16:](https://www.vaultproject.io/docs/install/index.html)
114-
115-
[Hashicorp Documentation: Production Hardening :octicons-link-external-16:](https://learn.hashicorp.com/vault/operations/production-hardening
116-
)
117-
115+
[Hashicorp Documentation: Installing Vault :octicons-link-external-16:](https://developer.hashicorp.com/vault/docs/install)
116+
117+
[Hashicorp Documentation: Production Hardening :octicons-link-external-16:](https://developer.hashicorp.com/vault/tutorials/operations/production-hardening)
118+
119+
## Related topics
120+
121+
* [Keyring components overview](keyring-components-plugins-overview.md)
122+
123+
* [Use the keyring file component](use-keyring-file.md)
124+
125+
* [Use the Key Management Interoperability Protocol (KMIP)](using-kmip.md)
126+
127+
* [Use the Amazon Key Management Service (AWS KMS)](using-amz-kms.md)
128+
129+
* [Data at rest encryption](data-at-rest-encryption.md)

‎docs/using-amz-kms.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,4 +90,16 @@ For more information, see [Finding the key ID and key ARN :octicons-link-externa
9090
}
9191
```
9292

93-
For more information, see [Keyring Component installation :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/keyring-component-installation.html).
93+
--8<--- "keyring-components-verification.md"
94+
95+
## Related topics
96+
97+
* [Keyring components overview](keyring-components-plugins-overview.md)
98+
99+
* [Use the keyring file component](use-keyring-file.md)
100+
101+
* [Use the keyring vault component](use-keyring-vault-component.md)
102+
103+
* [Use the Key Management Interoperability Protocol (KMIP)](using-kmip.md)
104+
105+
* [Data at rest encryption](data-at-rest-encryption.md)

‎docs/using-kmip.md‎

Lines changed: 89 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,28 @@
11
# Use the Key Management Interoperability Protocol (KMIP)
22

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)
5-
- [HashiCorp Vault Enterprise KMIP Secrets Engine :octicons-link-external-16:](https://developer.hashicorp.com/vault/docs/secrets/kmip)
6-
- [Thales CipherTrust Manager :octicons-link-external-16:](https://cpl.thalesgroup.com/encryption/ciphertrust-manager)
7-
- [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:
84

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)
106

11-
* Streamline encryption key management
7+
* [HashiCorp Vault Enterprise KMIP Secrets Engine :octicons-link-external-16:](https://developer.hashicorp.com/vault/docs/secrets/kmip)
128

13-
* Eliminate redundant key management processes
9+
* [Thales CipherTrust Manager :octicons-link-external-16:](https://cpl.thalesgroup.com/encryption/ciphertrust-manager)
10+
11+
* [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
1418

1519
## Component installation
1620

1721
--8<--- "keyring-components-installation.md"
1822

1923
For more information, see [Installing and Uninstalling Components :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/component-loading.html).
2024

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:
2226

2327
```json
2428
{
@@ -27,34 +31,96 @@ The following is an example of a global manifest file that does not use local ma
2731
}
2832
```
2933

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:
3135

3236
```json
3337
{
3438
"read_local_manifest": true
3539
}
3640
```
3741

38-
The following is an example of a local manifest file:
42+
The following example shows a local manifest file:
3943

4044
```json
4145
{
4246
"components": "file://component_keyring_kmip"
4347
}
4448
```
4549

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. The following example shows a configuration file:
51+
52+
```json
53+
{
54+
"server_addr": "127.0.0.1",
55+
"server_port": "5696",
56+
"client_ca": "client_certificate.pem",
57+
"client_key": "client_key.pem",
58+
"server_ca": "root_certificate.pem",
59+
"object_group": "",
60+
"kmip_timeout_ms": 5000,
61+
"tls_peer_verification": false,
62+
"tls_hostname_verification": false
63+
}
64+
```
65+
66+
### Configuration options
67+
68+
The configuration file for the KMIP keyring supports the following options:
69+
70+
| Option | Type | Default | Description |
71+
|---|---|---|---|
72+
| `server_addr` | string | Required | Hostname or IP address of the KMIP server |
73+
| `server_port` | string | Required | TCP port of the KMIP server, for example `"5696"` |
74+
| `client_ca` | string | Required | Path to the client certificate that the client presents to the KMIP server, in PEM (Privacy-Enhanced Mail) format |
75+
| `client_key` | string | Required | Path to the client private key that matches `client_ca`, in PEM format |
76+
| `server_ca` | string | Required | Path to the CA (certificate authority) certificate that verifies the KMIP server, in PEM format |
77+
| `object_group` | string | `""` | KMIP object group for registering and enumerating objects; empty value disables grouping |
78+
| `kmip_timeout_ms` | integer | `5000` | KMIP connection timeout in milliseconds |
79+
| `tls_peer_verification` | boolean | `false` | When `true`, verifies the KMIP server TLS (Transport Layer Security) certificate against `server_ca` |
80+
| `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 |
81+
82+
#### TLS verification
83+
84+
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.
85+
86+
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.
87+
88+
### Requirements for KMIP object states
89+
90+
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.
91+
92+
!!! important
93+
94+
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.
95+
96+
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.
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+
114+
--8<--- "keyring-components-verification.md"
115+
116+
## Related topics
117+
118+
* [Keyring components overview](keyring-components-plugins-overview.md)
119+
120+
* [Use the keyring file component](use-keyring-file.md)
47121

48-
??? example "Example of a configuration file in JSON format"
122+
* [Use the keyring vault component](use-keyring-vault-component.md)
49123

50-
```json
51-
{
52-
"server_addr": "127.0.0.1",
53-
"server_port": "5696",
54-
"client_ca": "client_certificate.pem",
55-
"client_key": "client_key.pem",
56-
"server_ca": "root_certificate.pem"
57-
}
58-
```
124+
* [Use the Amazon Key Management Service (AWS KMS)](using-amz-kms.md)
59125

60-
For more information, see [Keyring Component installation :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/keyring-component-installation.html).
126+
* [Data at rest encryption](data-at-rest-encryption.md)

‎snippets/keyring-components-installation.md‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,27 @@
11

2-
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.
33

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:
55

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 |
710

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
918

1019
2. Write a configuration file
1120

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.
1324

1425
!!! warning
1526

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.

‎snippets/keyring-components-verification.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
2+
## Verify the keyring component
3+
4+
After you start Percona Server for MySQL, confirm that the keyring component loaded and initialized. Query the `performance_schema.keyring_component_status` table:
5+
6+
```sql
7+
SELECT * FROM performance_schema.keyring_component_status;
8+
```
9+
10+
The query returns one row for each status key that the loaded component reports. The `Component_status` row indicates the result of initialization:
11+
12+
| `Component_status` value | Meaning | Recovery |
13+
|---|---|---|
14+
| `Active` | The component loaded and initialized successfully | None |
15+
| `Disabled` | The component loaded but failed to initialize, typically due to a configuration error | Review the server error log, correct the configuration file, then run `ALTER INSTANCE RELOAD KEYRING` |
16+
17+
If a keyring component fails to load entirely, the server does not start. Check the server error log for diagnostic messages.
18+
19+
For the complete list of status keys that each component reports, see [keyring_component_status Table :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/performance-schema-keyring-component-status-table.html) in the MySQL Reference Manual.

0 commit comments

Comments
 (0)