zkey kms configure for the KMIP plug-in

Use the zkey kms configure command to configure the KMIP plug-in.

In the following, the command is described as it applies when working with the KMIP plug-in. For the EKMF Web context, see zkey kms configure.

zkey kms configure syntax for KMIP

Read syntax diagramSkip visual syntax diagramzkey kms con-a, <adapter>.<domain>-c  <csr_pem>-n-C  <cert_pem>-d 30-d  <days>-s  <rdns>-e ; <name>=<value>-N  <cert_pem>-D  <digest>-r <cert_pem>-bCA certificates<ca_bundle>-S<KMIP_server>-p <profile_name>-w-B <label>TLS options-iECC: secp521r1ECC:  <curve>RSA:  <modulus-bits>-P
TLS options
Read syntax diagramSkip visual syntax diagram--tls-pin-server-pubkey--tls-trust-server-cert--tls-dont-verify-server-cert--tls-verify-hostname
where:
-a or --apqns <adapter.domain, adapter.domain,...>
Associates cryptographic adapters (APQNs) in either CCA or EP11 coprocessor mode with the key-management system plug-in. You can specify one or multiple APQNs in either CCA coprocessor mode or in EP11 coprocessor mode, but not both. Specify multiple APQNs as a comma-separated list. Each APQN consists of an adapter and domain number separated by a period. All APQNs that you want to set, add, or replace must be online.

To add an APQN to an existing list, prefix the APQN with a plus sign (+).

To remove an APQN from the associated APQNs, prefix the APQN with a minus sign (-).

To set or replace the APQN association, do not specify a prefix. You cannot mix plus and minus signs in one specification. You can either add, remove, or set the associations with one command.

-c or --gen-csr <csr_pem>

Generates a certificate signing request (CSR) with the identity key and stores it into the specified PEM file. You pass this CSR to a CA to have it issue a CA signed certificate for the KMIP plug-in. You need to register the certificate with the KMIP server before you can access it. Registering a client certificate with the KMIP server is a manual procedure, and is specific to the KMIP server used. The KMIP server accepts communication with the KMIP plug-in only after the certificate is registered. The CA-signed certificate is required for communicating with the KMIP server. Use the --client-cert option to specify it.

-n or --csr-new-header
Adds the word NEW to the PEM file header and footer lines on the CSR. Some software and some CAs need this marking.
-C or --gen-self-signed-cert <csr_pem>
Generates a self-signed certificate with the identity key and store it into the specified PEM file. You need to register the certificate with the key-management system before you can access it. You need to register the certificate with the KMIP server before you can access it. Registering a client certificate with the KMIP server is a manual procedure, and is specific to the KMIP server used. The KMIP server accepts communication with the KMIP plug-in only after the certificate is registered.
-d or --cert-validity-days <days>
Specifies the number of days the self-signed certificate is valid. The default is 30 days.
-s or --cert-subject <rdns>
Specifies the subject name for generating a CSR or self-signed certificate, in the form <type>=<value>(;<type>=<value>)*[;] with types recognized by OpenSSL.
-e or --cert-extensions <exts>
Specifies the certificate extensions for generating a CSR or self-signed certificate, in the form <name>=[critical,]<value>(;<name>=[critical,]<value>)*[;] with extension names and values recognized by OpenSSL.

A certificate used to authenticate at a KMIP server usually needs the TLS Web client authentication extended-key-usage certificate extension. Additionally, the Common Name field or the Subject Alternate Name extension must match the host name or IP address of the client system. If no extended-key-usage extension is specified, then a TLS Web client authentication extension ('extendedKeyUsage=clientAuth') is automatically added. If no Subject Alternate Name extension is specified, then a Subject Alternate Name extension with the system's host name (subjectAltName=DNS:hostname) is automatically added.

-D or --cert-digest <digest>
Specifies the digest algorithm to use when you generate a certificate-signing request or self-signed certificate. If this specification is omitted, the OpenSSL default is used.
-i or --gen-identity-key ECC:<curve> or RSA:<modulus-bits>
Generates an identity key for the KMIP plug-in. The identity key is a secure ECC or RSA key. An identity key is automatically generated with the default values ECC with curve secp521r1 when a CSR or self-signed certificate is to be generated and no identity key is available.

Use this option to generate or regenerate the identity key with specific parameters. You must regenerate a client certificate with the newly generated identity key and reregister this client certificate with the KMIP server.

−P or −−cert−rsa−pss
For identity-key type RSA: Uses the RSA−PSS algorithm to sign the certificate signing request (CSR) or the self−signed certificate.
−r or −−client−cert <cert_pem>
Uses a CA-signed certificate to authenticate the KMIP plug-in with the KMIP server. The certificate must be registered with the KMIP 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.
−S or −−kmip−server <KMIP_server>
Specifies the hostname or IP address of the KMIP server, and an optional port number separated by a colon. The default port number is 5696. To use HTTPS transport, specify the URL, starting with https://, followed by the hostname or IP address of the KMIP server, an optional port number, and a URI, for example /kmip.
−p or −−profile <profile_name>
Specifies the name of the KMIP plug-in profile to use with the KMIP server connection. If no profile name is specified, the KMIP plug-in queries the KMIP server information and attempts to match a profile to the information. If no profile matches, the default profile, default.profile is used. Profiles are contained in the directory /etc/zkey/kmip/profiles. You can set the location of the profiles with the environment variable ZKEY_KMIP_PROFILES.
-N or --renew-cert <cert_pem>
Specifies an existing PEM file that contains the certificate to be renewed. The certificate's subject name and extensions are used to generate the CSR or renewed self-signed certificate.
-b or --tls-ca-bundle <ca_bundle>
Specifies the CA bundle PEM file, or the directory that contains the CA certificates that are used to verify the key-management server certificate during the TLS handshake. If the option specifies a directory path, then this directory must be prepared with OpenSSL’s c_rehash utility.

The default is to use the system CA certificates.

--tls-pin-server-pubkey
For CA-signed server certificates: Pins the public key of the server. With a pinned key, it is verified that every connection uses the same key-management server certificate as the one used when the connection to the key-management server was configured.
--tls-trust-server-cert
Trusts the key-management server's certificate even if it is a self-signed certificate, or it was not verified due to other reasons. Use this option instead of the --tls-pin-server-pubkey option when you are using self-signed key-management server certificates.
--tls-dont-verify-server-cert
For self-signed key-management server certificates used in test environments: Bypasses the key-management server certificate verification by default. For CA-signed key-management server certificates, the default is to verify them.

This option overrides --tls-trust-server-cert.

--tls-verify-hostname
Verifies that the key-management server certificate's Common Name field or a Subject Alternate Name field matches the hostname that is used to connect to the key-management server.
−w or −−gen−wrapping−key
Generates a new wrapping key (key−encrypting key) based on the settings in the profile and registers it with the KMIP server. A wrapping key is automatically generated when the KMIP server connection is configured. Use this option to generate a new wrapping key later.
−B or −−label <label>
Specifies a human-readable identifier of the wrapping key that is stored in the Name KMIP attribute of the key. KMIP names must usually be unique within the KMIP server.
Examples
  • To configure the connection to the KMIP server on my.kmip.server, issue:
    zkey kms configure −−kmip−server my.kmip.server
  • To configure the connection to the KMIP server on my.kmip.server using HTTPS, issue:
    zkey kms configure −−kmip−server https://my.kmip.server/kmip
  • To configure the connection to the KMIP server on my.kmip.server and use the KMIP plug-in profile ABC, issue:
    zkey kms configure −−kmip−server my.kmip.server −−profile ABC
  • To configure the connection to the KMIP server on my.kmip.server and pin the server’s public key from the server’s TSL certificate as well as enable verification of the hostname to match the server’s Common Name in the certificate, issue:
    zkey kms configure −−kmip−server my.kmip.server −−tls−pin−server−pubkey −−tls−verify−hostname