Scroll to navigation

ZKEY-KMIP(1) General Commands Manual ZKEY-KMIP(1)

NAME

zkey-kmip - Key management system plugin for Key Management Interoperability Protocol (KMIP)

DESCRIPTION

The zkey-kmip.so library is a key management system plugin for zkey and provides an interface to KMIP servers. With this plugin, you can integrate external KMIP-based key management systems into zkey.

AES keys can be generated by a KMIP server and then imported into the zkey secure key repository as secure keys. The keys can be used to encrypt volumes, the same way as with secure AES keys generated by zkey locally.

The KMIP plugin supports secure keys of type CCA-AESDATA, CCA-AESCIPHER, and EP11-AES and requires one or multiple IBM cryptographic adapters in either CCA or EP11 coprocessor mode. You can configure the KMIP plugin with either one or multiple cryptographic adapters in CCA coprocessor mode, or with one or multiple cryptographic adapters in EP11 coprocessor mode, but not in a mixed setup. Cryptographic adapters in CCA coprocessor mode support secure keys of type CCA-AESDATA and CCA-AESCIPHER. Cryptographic adapters in EP11 coprocessor mode support secure keys of type EP11-AES.

Note: Secure keys of type CCA-AESDATA and CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C. Secure keys of type EP11-AES require an IBM cryptographic adapter in EP11 coprocessor mode of version 7 or later, e.g. a CEX7P.

Bind the zkey secure key repository to the KMIP plugin

To use a KMIP server with zkey, first bind the zkey secure key repository to the KMIP key management system plugin.

Use the zkey kms plugins command to list available key management system plugins. The KMIP plugin appears as plugin KMIP in the list of available plugins. If it does not appear, check if it is configured properly in the /etc/zkey/kms-plugins.conf configuration file. Refer to the zkey man page for details about the configuration file.

Use the zkey kms bind KMIP command to bind the KMIP key management system plugin to the zkey repository. You must then configure the KMIP plugin with the command zkey kms configure before it can be used.

Display information about the KMIP key management system plugin

Use the zkey kms info command to display information about the KMIP key management system plugin and its configuration. If any of the settings are displayed as '(configuration required)', then you must configure these settings before you can use the KMIP plugin. Use the zkey kms configure command to do so.

Configure the KMIP key management system plugin

Use the zkey kms configure command to configure or reconfigure the KMIP key management system plugin. Use command zkey kms configure --help to display the possible command-line options to perform the configuration.

Configuring the KMIP plugin may be a multi-step task. You can supply all configuration options at once or use the zkey kms configure command several times supplying only one or a few configuration options each time.

The following settings must be configured:

  • The cryptographic adapters (APQNs) associated with the KMIP key management system plugin. These APQNs are used by the KMIP plugin to generate internally used secure keys, such as the identity key and the wrapping key. The APQNs are also used to import AES keys from the KMIP server into the zkey repository, as secure AES keys enciphered with the current CCA or EP11 master key. Secure keys that are imported from KMIP are automatically associated with the APQNs of the KMIP plugin. Use the --apqns option to specify the APQNs to be associated with the KMIP plugin. You can associate either one or multiple APQNs in either CCA coprocessor mode or in EP11 coprocessor mode, but not both types at the same time.
  • The secure identity key used to authenticate the zkey client with the KMIP server through TLS client authentication. The identity key is a secure ECC or RSA key. The identity key is automatically generated using the defaults (ECC with curve secp521r1) when a certificate signing request (CSR) or self-signed certificate is to be generated and no identity key is available. If you need to generate or regenerate the identity key with specific parameters, use option --gen-identity-key. You must regenerate a client certificate with the newly generated identity key and reregister this client certificate with the KMIP server.
  • The client certificate to authenticate the zkey client with the KMIP server. The client certificate is an X.509 certificate that is generated with the secure identity key of the KMIP key management system plugin. To generate a certificate signing request (CSR) with the identity key, use option --gen-csr. Pass this CSR to a certificate authority (CA) to request a CA-signed certificate for the KMIP plugin. Then, specify the CA-signed certificate with the --client-cert option so that the KMIP plugin uses it for communicating with the KMIP server. Alternatively, use the --gen-self-signed-cert option to generate a self-signed certificate with the identity key for the KMIP plugin. Use options --cert-subject and --cert-extensions to specify the certificate subject name and optionally certificate extensions. To renew an existing certificate, use the --renew-cert option. The subject name and certificate extensions are then copied from the certificate that is to be renewed. You need to register the client certificate with the KMIP server. 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 plugin only after the certificate is registered.
  • The connection to the KMIP server. The KMIP plugin communicates with the KMIP server through the KMIP protocol over Transport Layer Security (TLS) or Hypertext Transfer Protocol Secure (HTTPS). Use the --kmip-server option to specify the hostname or IP address of the KMIP server, and optionally a port number separated by a colon. If no port number is specified, 5696 is used for KMIP. 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 an URI (for example '/kmip'). Specify TLS-specific options to control the behavior of the TLS protocol and the validation of the KMIP server's certificate. Use the zkey kms configure --help command to display the possible command-line options.
  • The KMIP server settings, such as the KMIP server information string, and the supported KMIP protocol version are queried when the connection is configured. Based on the KMIP server information string returned by the KMIP server, a KMIP plugin profile is tried to be matched. To use a specific KMIP plugin profile, specify one with the --profile option together with the --kmip-server option. For more information about plugin profiles, see the section KMIP plugin profiles below.
  • The key-wrapping key used to wrap (encrypt) AES keys retrieved from the KMIP server. The wrapping key is a secure RSA key, and is automatically generated when the KMIP server connection is configured. The public key of the wrapping key is registered with the KMIP server. Use the --gen-wrapping-key option to generated and register a new wrapping key.

Reencipher the secure identity and wrapping keys

Use the zkey kms reencipher command to reencipher the secure identity key and the secure wrapping key of the KMIP key management system plugin with a new master key. The secure identity and wrapping keys must be reenciphered when the master keys of the associated APQNs in cryptographic adapters change.

  • For cryptographic adapters in CCA coprocessor mode, this is the APKA master key.
  • For cryptographic adapters in EP11 coprocessor mode, this is the EP11 master key.

See the man page of zkey for a description of the zkey kms reencipher command.

Note: The zkey kms reencipher command does not reencipher secure keys that were generated by, or have been imported from, the KMIP server, and are now stored in the secure key repository. Use the regular zkey reencipher command to reencipher those secure keys.

Generating secure AES keys with KMIP

Use the zkey generate command to generate secure AES keys in the KMIP server and import the newly generated keys into the secure key repository. When the zkey repository is bound to the KMIP key management system plugin, then the zkey generate command always generates the keys in the KMIP server, unless the --local option is specified.

Keys that are generated in the KMIP server always match the type of the APQNs associated with the KMIP plugin. When cryptographic adapters in CCA coprocessor mode are associated with the KMIP plugin, secure keys of type CCA-AESDATA, and CCA-AESCIPHER are generated. When cryptographic adapters in EP11 coprocessor mode are associated with the KMIP plugin, secure keys of type EP11-AES are generated. A generated key inherits the APQNs from the plugin. You cannot associate different APQNs to a key that is bound to the KMIP plugin. Specify the --key-type option with the zkey generate command to generate a key of a specific type. The default type is CCA-AESDATA when the associated adapters are in CCA coprocessor mode, and EP11-AES when the associated adapters are in EP11 coprocessor mode.

To specify an optional name for the generated key in the KMIP server, use the --label option. The specified name is stored in the Name KMIP attribute of the key. KMIP names must be unique within the KMIP server. For XTS type keys, two different labels must be specified, separated by a colon. If the --label option is omitted, the unique IDs assigned by the KMIP server to the generated keys are used to identify the keys.

Other information can be associated with a secure key, by using the --description, --volumes, --volume-type, or --sector-size options. This associated information is also stored in the KMIP server in KMIP attributes of the key.

Remove secure keys that are bound to the KMIP plugin from the key repository

Use the zkey remove command to remove an existing secure key from the secure key repository. You can change the state of a key that is bound to the KMIP key management system plugin while removing it. Use the --state option to specify the new state of the key. If no state is specified, the key remains unchanged in the KMIP server, and is removed from the local secure key repository only.

Change secure keys that are bound to the KMIP plugin

Use the zkey change command to change the description, the associated volumes, the sector size, and the volume type of a secure key in the secure key repository. If the key is bound to the KMIP key management system plugin, then the related KMIP attributes of the key are also updated in the KMIP server.

A key inherits the APQNs from the plugin. You cannot change the associated cryptographic adapters (APQNs) for a key that is bound to the KMIP plugin. To change the APQNs associated with the KMIP plugin, use the zkey kms configure command with the --apqns option. Changing the APQNs for the plugin also changes the APQN associations of all secure keys in the secure key repository that are bound to the KMIP plugin.

Rename secure keys that are bound to the KMIP plugin

Use the zkey rename command to rename an existing secure key in the secure key repository. If the key is bound to the KMIP key management system plugin, then the related KMIP attributes of the key are also updated in the KMIP server. The key label as it is known in the KMIP Server cannot be changed. Only the associated zkey name is updated.

List secure keys that are managed by the KMIP plugin

Use the zkey kms list command to display eligible secure keys managed by the KMIP server. You can filter the displayed list by key label, key name, associated volumes, and volume type. Refer to the man page of zkey for the details on these filter options.

Note: It is specific to the KMIP server implementation how keys are associated to certain clients or groups of clients, and how to control which clients can see and access which keys. Refer to the documentation of your KMIP server for more details about how to control access to keys in the KMIP server.

Import secure keys that are managed by the KMIP server into the repository

Use the zkey kms import command to import secure keys managed by the KMIP server into the secure key repository. You can filter the list of keys to be imported by key label, key name, associated volumes, and volume type. Refer to the man page of zkey for the details on these filter options.

Note: It is specific to the KMIP server implementation how keys are associated to certain clients or groups of clients, and how to control which clients can see and access which keys. Refer to the documentation of your KMIP server for more details about how to control access to keys in the KMIP server.

Refresh secure keys that are bound to the KMIP plugin

Use the zkey kms refresh command to refresh secure keys that are bound to the KMIP key management system plugin. You can filter the list of keys to be refreshed by name, associated volumes, volume type, and key type. Refreshing a key updates the secure key by reimporting it from the KMIP server. Use the --refresh-properties option to also update the associated information, such as the textual description, associated volumes, volume type, and sector size, with the information stored in the KMIP server. Refer to the man page of zkey for the details on the zkey kms refresh command.

The zkey kms refresh command can also help if the secure keys have not been reenciphered properly after a CCA or EP11 master key change, and thus became invalid. The zkey kms refresh command reimports the secure key under the current CCA or EP11 master key. Hence, you can use this command as an alternative to the zkey reencipher command for keys that are bound to KMIP plugin.

OPTIONS

The following zkey options are specific to the KMIP key management system plugin. Refer to the zkey man page for other options.

Options for the zkey kms configure command

Generates an identity key for the KMIP plugin. The identity key is a secure ECC or RSA key. The identity key is automatically generated with the default values ECC with curve secp521r1 when a certificate signing request (CSR) or self-signed certificate is to be generated and no identity key is available. If you need to generate or regenerate the identity key with specific parameters, use option --gen-identity-key. You must regenerate a client certificate with the newly generated identity key and reregister this client certificate with the KMIP server.
Generates a certificate signing request (CSR) with the identity key and stores it in the specified PEM file. Pass this CSR to a certificate authority (CA) to request a CA-signed certificate for the KMIP plugin. You need to register the certificate with the KMIP server. 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 plugin only after the certificate is registered. You must also specify the CA-signed certificate with the --client-cert option so that the KMIP plugin uses it for communicating with the KMIP server.
Generates a self-signed certificate with the identity key and stores it in the specified PEM file. You need to register the certificate with the KMIP server. 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 plugin only after the certificate is registered.
Specifies the subject name for generating a certificate signing request (CSR) or self-signed certificate, in the form <type>=<value>(;<type>=<value>)*[;] with types recognized by OpenSSL.
Specifies the certificate extensions for generating a certificate signing request (CSR) or self-signed certificate, in the form <name>=[critical,]<value(s)>(;<name>=[critical,]<value(s)>)*[;] 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.
Specifies an existing PEM file that contains the certificate to be renewed. The subject name and extensions of the certificate are used to generate the certificate signing request (CSR) or renewed self-signed certificate.
Adds the word NEW to the PEM file header and footer lines on the certificate signing request. Some software and some CAs require this marking.
Specifies the number of days the self-signed certificate is valid. The default is 30 days.
Specifies the digest algorithm to use when generating a certificate signing request (CSR) or self-signed certificate. The default is determined by OpenSSL.
Uses the RSA-PSS algorithm to sign the certificate signing request (CSR) or the self-signed certificate. This option is accepted only when the identity key type is RSA, it is ignored otherwise.
Uses a CA-signed certificate to authenticate the KMIP plugin with the KMIP server. The certificate must be registered with the KMIP server. 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 plugin only after the certificate is registered.
Specifies the hostname or IP address of the KMIP server, and an optional port number separated by a colon. If no port number is specified, 5696 is used for KMIP. 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 an URI (for example /kmip).
Specifies the name of the KMIP plugin profile to use with the KMIP server connection. If no profile name is specified, the KMIP plugin queries the KMIP server information and attempts to match a profile to the information. If no profile matches, the default profile is used. Profiles are contained in the directory /etc/zkey/kmip/profiles. You can set the location of the profiles by using the environment variable ZKEY_KMIP_PROFILES.
Specifies the CA-bundle PEM file or directory containing the CA certificates that are used to verify the KMIP server certificate during TLS handshake. If the option specifies a directory path, the directory must be prepared with the c_rehash utility of OpenSSL. Default is to use the system CA certificates.
Pins the public key of the KMIP server. With a pinned key, the KMIP plugin verifies that every connection uses the same KMIP server-certificate public key that was also used to configure the connection to the KMIP server. This option can be used only with CA-signed KMIP server certificates.
Trusts the certificate of the KMIP server even if it is a self-signed certificate, or it can not be verified due to other reasons. Use this option instead of the --tls-pin-server-pubkey option when you are using self-signed KMIP server certificates.
Do not verify the authenticity of the certificate of the KMIP server. For self-signed KMIP server certificates, this is the default. Use the --tls-pin-server-cert option to ensure the authenticity of the self-signed certificate explicitly. For CA-signed KMIP server certificates, the default is to verify them. This option disables the verification.
Verifies that the KMIP server certificate�s Common Name field or a Subject Alternate Name field matches the hostname that is used to connect to the KMIP server.
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 at a later time.
Specifies an optional human-readable identifier of the wrapping key stored in the Name KMIP attribute of the key. KMIP names must usually be unique within the KMIP server.

Options for the zkey generate command

Specifies an optional human-readable identifier of the key or keys stored in the Name KMIP attribute of the key. KMIP names must usually be unique within the KMIP server. For XTS type keys, two different labels must be specified, separated by a colon.

Options for the zkey remove command

Specifies the state to which to change the key in the KMIP server, after removing the secure key from the local secure key repository. Possible states are DEACTIVATED, COMPROMISED, DESTROYED, and DESTROYED-COMPROMISED. If this option is not specified, the state of the key in the KMIP server is not changed, but the key is removed from the local secure key repository only.

Options for the zkey kms import command

Specifies the type of the key to import. Possible values are CCA-AESDATA, CCA-AESCIPHER, and EP11-AES. The key type must be matching to the type of APQNs associated with the KMIP plugin. When cryptographic adapters in CCA coprocessor mode are associated with the KMIP plugin, secure keys of type CCA-AESDATA, and CCA-AESCIPHER are supported. When cryptographic adapters in EP11 coprocessor mode are associated with the KMIP plugin, secure keys of type EP11-AES are supported. When this option is omitted, the default is CCA-AESDATA when cryptographic adapters in CCA coprocessor mode are associated with the KMIP plugin, and EP11-AES when cryptographic adapters in EP11 coprocessor mode are associated with the KMIP plugin.

KMIP PLUGIN PROFILES

This section describes the KMIP plugin profiles. A KMIP plugin profile controls certain parameters and settings for communicating with the KMIP server. A KMIP plugin profile usually belongs to a certain KMIP server product or implementation, and contains settings to be used for that specific KMIP server implementation.

Note: KMIP plugin profiles must not be confused with the KMIP profiles as defined by the KMIP standard.

A KMIP plugin profile is selected when configuring the connection to the KMIP server. Either, a profile name is explicitly specified using the --profile option of the zky kms configure command together with the --kmip-server option, or a profile is automatically selected based on the KMIP server information string that the KMIP server returned with the KMIP QUERY command response. If none of the available profiles match to the KMIP server information string, the default profile is used.

KMIP plugin profiles are text files with a naming scheme like product-name.profile and are located in directory /etc/zkey/kmip/profiles. The profiles location can be overridden with environment variable ZKEY_KMIP_PROFILES. At least the default profile must exist, i.e. in file default.profile. Users may supply own profiles, in addition to the profiles provided together with the KMIP plugin. If you are a KMIP server provider, and you want a KMIP plugin profile for your KMIP server to be added, open an issue or a pull request at https://github.com/ibm-s390-linux/s390-tools and supply a profile for your KMIP server.

The following parameters and settings are specified in a KMIP plugin profile:

  • A regular expression to match the KMIP server information string with. If the regular expression matches the server information string when the KMIP server is configured, the profile is selected.
  • The KMIP protocol version to use. This can be either a specific KMIP protocol version like major.minor or AUTO. When AUTO is specified, the KMIP protocol version supported by the KMIP server is automatically discovered using the DISCOVER VERSIONS KMIP request.
  • The transport method. Possible values are TSL or HTTPS. A transport method of HTTPS can also be selected by specifying an URL beginning with https:// with the --kmip-server option with the zkey kms configure command, even if the profile used specifies TLS.
  • The encoding method for the KMIP protocol. Possible values are TTLV, JSON, or XML. JSON and XML encoding are only posisble with the HTTPS transport method.
  • The default URI used for the HTTPS transport method, e.g. /kmip. The URI can be overridden with the --kmip-server option with the zkey kms configure command. This setting is ignored if the transport method is not HTTPS.
  • The authentication scheme. Currently only TLS client authentication is supported.
  • The key wrapping algorithm for retrieving keys from the KMIP server. Currently only RSA is supported.
  • The RSA modulus size of the RSA wrapping key in bits. Possible values are 512, 1024, 2048, and 4096 bits.
  • The key format used to register the public wrapping key with the KMIP server. Possible values are PKCS #1, PKCS #8, and Transparent Public Key.
  • The padding method used with RSA key wrapping. Possible values are PKCS #1.5 or OAEP.
  • The hashing algorithm used with RSA key wrapping with the OAEP padding method. The specified hashing algorithm is used for both, the OAEP message hash as well as the mask generator function (MGF). Possible values are SHA-1 and SHA-256.
  • Specifies if the KMIP server supports the KMIP Link attribute. If TRUE, the KMIP plugin uses KMIP Link attributes to link the 2 keys of an XTS key together. Otherwise, KMIP custom/vendor attributes with a zkey specific name are used.
  • Specifies if the KMIP server supports the KMIP Description attribute. If not supported, the KMIP plugin uses the KMIP Comment attribute (if supported), or a KMIP custom/vendor attribute with a zkey specific name.
  • Specifies if the KMIP server supports the KMIP Comment attribute. If not supported, the KMIP plugin uses a KMIP custom/vendor attribute with a zkey specific name instead.
  • Specifies the custom/vendor attribute scheme for KMIP servers supporting the KMIP protocol version 2.0 or higher. Possible values are v1-style and v2-style. For v1-style, the attribute's Vendor Identifier is set to x, and Attribute Name is set to zkey-<something>. This corresponds to the KMIP custom attribute style of the KMIP protocol version 1.0 - 1.4. For v2-style, the attribute's Vendor Identifier is set to zkey, and Attribute Name is set to <something>.
  • Specifies if the KMIP server supports the KMIP Sensitive attribute. If TRUE, all keys are generated with Sensitive=True to prevent the key from being retrieved in clear from the KMIP server.
  • Specifies if the KMIP server supports the KMIP Always Sensitive attribute. If TRUE, all keys retrieved from the KMIP server are checked to have Always Sensitive=True to ensure that the key was never able to be retrieved in clear from the KMIP server.

EXAMPLES

Lists available key manamgement system plugins.
Binds the KMIP plugin to the current secure key repository.
Configures the APQN '03.004c' to be associated with the KMIP plugin.
Generates an RSA identity key with a modulus size of 4096 bits.
Generates an ECC identity key with ellitic curve secp521r1.
Generates a certificate signing request with the identity key and the specified subject name and stores it in file 'csr.pem'.
Generates a certificate signing request with the identity key to renew the existing certificate in file cert.pem and stores it in file 'csr.pem'.
Generates a self-signed certificate with the identity key and the specified subject name and a validity of 50 days, and stores it in file 'cert.pem'.
Generates a self-signed certificate with the identity key and the specified subject name and a certificate extension to limit the key usage, and stores it in file 'cert.pem'.
Use the CA-signed client certificate in file 'cert.pem' with the KMIP plugin.
Configures the connection to the KMIP server on 'my.kmip.server'.
https://my.kmip.server/kmip
Configures the connection to the KMIP server on 'my.kmip.server' using HTTPS transport.
Configures the connection to the KMIP server on 'my.kmip.server' and use the KMIP plugin profile 'ABC'.
Configures the connection to the KMIP server on 'my.kmip.server' and pins the server's public key from the server's TSL certificate as well as enables verification of the host name to match the server's Common Name in the certificate.
Displays information about the KMIP plugin and its configuration.
Reenciphers the KMIP Plugin's identity key with a new master key in staged mode
Generates a secure AES key in the KMIP server using the label 'TEST' and stores it in the secure key repository using the name 'seckey' and associates it with block device '/dev/dasdc1' and device-mapper name 'encvol'.
Generates a secure AES key for the XTS cipher mode in the KMIP server using the labels 'TEST1' and 'TEST2' and stores it in the secure key repository using the name 'seckey' and associates it with block device '/dev/dasdc1' and device-mapper name 'encvol', and a volume type of luks2.
Removes secure key 'seckey' from the repository and sets the state of the key to 'DEACTIVATED' in the KMIP server.
Displays eligible secure keys managed by KMIP server.
Displays eligible secure keys managed by the KMIP server where the label name in the KMIP server contains the word 'LUKS2'.
Imports the secure key managed by the KMIP server with a zkey name of 'seckey'.
Imports secure keys managed by the KMIP server that are associated with volumes of volume type LUKS2.
Refreshes secure keys from the KMIP server where the name starts with 'sec'.
Refreshes the secure key with the name 'seckey' from the KMIP server and also refreshes the key properties.

ENVIRONMENT

If $ZKEY_KMIP_PROFILES is set, it specifies the location of the KMIP plugin profiles. If it is not set, then the default location of the KMIP plugin profiles is /etc/zkey/kmip/profiles.
June 2021 s390-tools