Configuring the KMIP plug-in

Edit online

Configuring the KMIP plug-in entails configuring AP queues, identity key information, and the KMIP server information.

About this task

The following must be configured for a KMIP plug-in:

AP queues
Supported key types
Identity key information (type, size, curve)
Client certificate information
KMIP server information (host name, vendor string, KMIP Version, transport/encoding)
TLS settings
(Optional) Wrapping key information (type, size, unique ID in KMIP)

For more details about the zkey kms command, see zkey kms - Managing secure keys with a KMS plug-in.

Procedure

Optional: Check which plug-ins are available. Issue the zkey kms plugins command, for example:
```
# zkey kms plugins
KMS-Plugin                Shared library
---------------------------------------------------
KMIP                      zkey-kmip.so
```
The example shows that the KMIP plug-in is available. It also shows the shared library that implements the plug-in.
To bind to the KMIP plug-in, issue the following command:
```
# zkey kms bind KMIP
```
The local secure key repository is bound to a key management system of type KMIP.
Note: A secure key repository can be bound to only one key management system.
Associate AP queues with the key-management plug-in.
You can specify either CCA or EP11 AP queues, but not both. To specify the AP queues to associate with the KMIP plug-in, use a command of the form:
```
# zkey kms configure --apqns <adapter1.domain1,adapter2.domain2,...>
```
The AP queue is defined by its adapter ID and domain ID. If you specify multiple AP queues, they must have the same master key.
For example, to add AP queues from adapter 08 and 09, both with domain 002f, issue:
```
# zkey kms configure --apqns 08.002f,09.002f
```
To see whether the AP queues are configured, use zkey kms info:
```
# zkey kms info
KMS-Plugin:             KMIP
  Supported key types:  CCA-AESCIPHER
  APQNs:                08.002f
                        09.002f
  KMIP server:         (configuration required)
```
Create a client certificate for communication with the KMIP server.
You must register the certificate with the server. The KMIP server accepts communication with the client only after the client’s certificate is registered.
1. Generate a certificate-signing request (CSR).
  Issue a command of the form:
```
# zkey kms configure  --gen-csr <request_file> --cert-subject  <subject>
```
  For example, to generate a certificate-signing request with a new identity key that uses the defaults ECC and secp521r1, and store it in a file that is named csr.pem, issue:
```
# zkey kms configure --gen-csr csr.pem --cert-subject SUBJECT-RDNS
```
  The generated CSR is stored into the specified csr.pem file.
  Alternative for test setups: You can use the --gen-self-signed-cert option to generate a self-signed certificate with the identity key for the KMIP plug-in. Self-signed certificates should be used for testing only. Use the --cert-subject to specify the certificate subject name, and optionally the --cert-extensions option to specify extensions.
2. Have a CA sign this request and issue a client certificate.
Register the client certificate to use for communication with the server. The detailed registration steps depends on the KMIP server. Refer to your server documentation for details and use the zkey kms info command to display information about the server and its configuration.
Issue a command of the form:
```
# zkey kms configure --client-cert <client_certificate>
```
For example, assume that the client certificate is stored in a file called CERT-PEM-FILE. Issue:
```
# zkey kms configure --client-cert CERT-PEM-FILE
```
Configure the KMIP server that you want to communicate with.
This step assumes that the client certificate has been set up and registered with the KMIP server.
Use the TLS options to pin the server, ensuring that it is always the same server in future communication.
```
# zkey kms configure --kmip-server <KMIP_server> --tls-pin-server-pubkey
```
You can specify a KMIP server profile. For more information about profiles, see KMIP plug-in profiles.

Results

The connection to the server is established, and information from the server is retrieved. An RSA key pair is generated automatically when the KMIP server connection is configured. The private key of this pair will be used as a wrapping key for retrieving keys from KMIP. The public key is retrieved by the KMIP plug-in, and stored in the zkey key repository, and is used for unwrapping the retrieved keys.

If you need to, you can generate a new wrapping key at any time. Use the command 'zkey kms configure --gen-wrapping-key [--label <name>] to re-generate a wrapping key.

Use the --label option to provide a human-readable name for the key.