.\" Copyright IBM Corp. 2021
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH ZKEY\-KMIP 1 "June 2021" "s390-tools"
.SH NAME
zkey\-kmip \- Key management system plugin for Key Management
Interoperability Protocol (KMIP)
.
.
.
.SH DESCRIPTION
The \fBzkey\-kmip.so\fP library is a key management system plugin for
\fBzkey\fP and provides an interface to KMIP servers. With this plugin, you can
integrate external KMIP\-based key management systems into zkey.
.PP
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.
.PP
The KMIP plugin supports secure keys of type \fBCCA\-AESDATA\fP,
\fBCCA\-AESCIPHER\fP, and \fBEP11\-AES\fP and requires one or multiple
IBM cryptographic adapters in either \fBCCA\fP or \fBEP11\fP coprocessor
mode. You can configure the KMIP plugin with either one or multiple
cryptographic adapters in \fBCCA\fP coprocessor mode, or with one or multiple
cryptographic adapters in \fBEP11\fP coprocessor mode, but not in a mixed setup.
Cryptographic adapters in \fBCCA\fP coprocessor mode support secure keys of
type \fBCCA\-AESDATA\fP and \fBCCA\-AESCIPHER\fP. Cryptographic adapters in
\fBEP11\fP coprocessor mode support secure keys of type \fBEP11\-AES\fP.
.PP
.B Note:
Secure keys of type \fBCCA\-AESDATA\fP and \fBCCA\-AESCIPHER\fP require an IBM
cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a
CEX6C. Secure keys of type \fBEP11\-AES\fP require an IBM cryptographic
adapter in EP11 coprocessor mode of version 7 or later, e.g. a CEX7P.
.
.SS "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.
.PP
Use the \fBzkey kms plugins\fP command to list available key management system
plugins. The KMIP plugin appears as plugin \fBKMIP\fP in the list of
available plugins. If it does not appear, check if it is configured properly in
the \fB/etc/zkey/kms\-plugins.conf\fP configuration file. Refer to the
\fBzkey\fP man page for details about the configuration file.
.PP
Use the \fBzkey kms bind KMIP\fP command to bind the KMIP key management
system plugin to the zkey repository. You must then configure the KMIP plugin
with the command \fBzkey kms configure\fP before it can be used.
.
.SS "Display information about the KMIP key management system plugin"
.
Use the \fBzkey kms info\fP command to display information about the KMIP
key management system plugin and its configuration. If any of the settings are
displayed as \fB'(configuration required)'\fP, then you must configure these
settings before you can use the KMIP plugin. Use the \fBzkey kms configure\fP
command to do so.
.
.SS "Configure the KMIP key management system plugin"
.
Use the \fBzkey kms configure\fP command to configure or reconfigure the
KMIP key management system plugin. Use command \fBzkey kms configure \-\-help\fP
to display the possible command\-line options to perform the configuration.
.PP
Configuring the KMIP plugin may be a multi\-step task. You can supply all
configuration options at once or use the \fBzkey kms configure\fP command
several times supplying only one or a few configuration options each time.
.PP
The following settings must be configured:
.RS 2
.IP "\(bu" 2
The \fBcryptographic adapters (APQNs)\fP 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 \fB\-\-apqns\fP 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.
.
.IP "\(bu" 2
The secure \fBidentity key\fP 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 \fB\-\-gen\-identity\-key\fP. You must regenerate a client
certificate with the newly generated identity key and reregister this client
certificate with the KMIP server.
.
.IP "\(bu" 2
The \fBclient certificate\fP 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 \fBcertificate signing request\fP (CSR) with the identity key,
use option \fB\-\-gen\-csr\fP. 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 \fB\-\-client\-cert\fP option so that the KMIP
plugin uses it for communicating with the KMIP server.
.
Alternatively, use the \fB\-\-gen\-self\-signed\-cert\fP option to generate a
\fBself\-signed certificate\fP with the identity key for the KMIP plugin.
Use options \fB\-\-cert\-subject\fP and \fB\-\-cert\-extensions\fP to specify
the certificate subject name and optionally certificate extensions. To renew an
existing certificate, use the \fB\-\-renew\-cert\fP 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.
.
.IP "\(bu" 2
The \fBconnection to the KMIP server\fP. 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
\fB\-\-kmip\-server\fP 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, \fB5696\fP is used for KMIP. To use HTTPS transport, specify the URL,
starting with \fB'https://'\fP, followed by the hostname or IP address of the
KMIP server, an optional port number, and an URI (for example \fB'/kmip\fP').
.
Specify TLS\-specific options to control the behavior of the TLS protocol and
the validation of the KMIP server's certificate. Use the \fBzkey kms configure
\-\-help\fP command to display the possible command\-line options.
.
.IP "\(bu" 2
The \fBKMIP server settings\fP, 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 \fBKMIP plugin profile\fP is tried to be matched. To use a specific
KMIP plugin profile, specify one with the \fB\-\-profile\fP option together
with the \fB\-\-kmip\-server\fP option. For more information about plugin
profiles, see the section \fBKMIP plugin profiles\fP below.
.
.IP "\(bu" 2
The \fBkey\-wrapping key\fP 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
\fB\-\-gen\-wrapping\-key\fP option to generated and register a new wrapping
key.
.RE
.
.SS "Reencipher the secure identity and wrapping keys"
.
Use the \fBzkey kms reencipher\fP 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.
.RS 2
.IP "\(bu" 2
For cryptographic adapters in \fBCCA\fP coprocessor mode, this is the \fBAPKA
master key\fP.
.IP "\(bu" 2
For cryptographic adapters in \fBEP11\fP coprocessor mode, this is the \fBEP11
master key\fP.
.RE
.PP
See the man page of \fBzkey\fP for a description of the \fBzkey kms
reencipher\fP command.
.PP
\fBNote:\fP The \fBzkey kms reencipher\fP command does \fBnot\fP 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 \fBzkey
reencipher\fP command to reencipher those secure keys.
.
.SS "Generating secure AES keys with KMIP"
.
Use the \fBzkey generate\fP 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
\fBzkey generate\fP command always generates the keys in the KMIP server,
unless the \fB\-\-local\fP option is specified.
.PP
Keys that are generated in the KMIP server always match the type of the APQNs
associated with the KMIP plugin. When cryptographic adapters in \fBCCA\fP
coprocessor mode are associated with the KMIP plugin, secure keys of type
\fBCCA\-AESDATA\fP, and \fBCCA\-AESCIPHER\fP are generated. When cryptographic
adapters in \fBEP11\fP coprocessor mode are associated with the KMIP plugin,
secure keys of type \fBEP11\-AES\fP 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 \fB\-\-key\-type\fP option with the
\fBzkey generate\fP command to generate a key of a specific type. The default
type is \fBCCA\-AESDATA\fP when the associated adapters are in \fBCCA\fP
coprocessor mode, and \fBEP11\-AES\fP when the associated adapters are in
\fBEP11\fP coprocessor mode.
.PP
To specify an optional name for the generated key in the KMIP server, use the
\fB\-\-label\fP option. The specified name is stored in the \fBName\fP 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 \fB\-\-label\fP option is omitted, the unique IDs assigned by the KMIP
server to the generated keys are used to identify the keys.
.PP
Other information can be associated with a secure key, by using the
\fB\-\-description\fP, \fB\-\-volumes\fP, \fB\-\-volume\-type\fP, or
\fB\-\-sector\-size\fP options. This associated information is also stored in
the KMIP server in KMIP attributes of the key.
.
.SS "Remove secure keys that are bound to the KMIP plugin from the key repository"
.
Use the \fBzkey remove\fP 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 \fB\-\-state\fP
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.
.
.SS "Change secure keys that are bound to the KMIP plugin"
.
Use the \fBzkey change\fP 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.
.PP
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 \fBzkey kms
configure\fP command with the \fB\-\-apqns\fP 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.
.
.SS "Rename secure keys that are bound to the KMIP plugin"
.
Use the \fBzkey rename\fP 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.
.
.SS "List secure keys that are managed by the KMIP plugin"
.
Use the \fBzkey kms list\fP 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 \fBzkey\fP for
the details on these filter options.
.PP
\fBNote:\fP 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.
.
.SS "Import secure keys that are managed by the KMIP server into the repository"
.
Use the \fBzkey kms import\fP 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 \fBzkey\fP for the details on these filter options.
.PP
\fBNote:\fP 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.
.
.SS "Refresh secure keys that are bound to the KMIP plugin"
.
Use the \fBzkey kms refresh\fP 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
\fB\-\-refresh\-properties\fP 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
\fBzkey\fP for the details on the \fBzkey kms refresh\fP command.
.PP
The \fBzkey kms refresh\fP 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 \fBzkey kms refresh\fP command reimports the secure key
under the current CCA or EP11 master key. Hence, you can use this command as an
alternative to the \fBzkey reencipher\fP command for keys that are bound to KMIP
plugin.
.
.
.
.SH OPTIONS
The following \fBzkey\fP options are specific to the KMIP key management system
plugin. Refer to the \fBzkey\fP man page for other options.
.
.SS "Options for the zkey kms configure command"
.TP
.BR \-i ", " \-\-gen\-identity\-key\~\fIECC:curve\fP | \fIRSA:modulus\-bits\fP
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 \fB\-\-gen\-identity\-key\fP. You must regenerate a client
certificate with the newly generated identity key and reregister this client
certificate with the KMIP server.
.TP
.BR \-c ", " \-\-gen\-csr\~\fIcsr\-pem\-file\fP
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 \fB\-\-client\-cert\fP option so that the KMIP plugin uses it for
communicating with the KMIP server.
.TP
.BR \-C ", " \-\-gen\-self\-signed\-cert\~\fIcert\-pem\-file\fP
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.
.TP
.BR \-s ", " \-\-cert\-subject\~\fIsubject\-rdns\fP
Specifies the subject name for generating a certificate signing request (CSR)
or self\-signed certificate, in the form
\fB<type>=<value>(;<type>=<value>)*[;]\fP with types recognized by OpenSSL.
.TP
.BR \-e ", " \-\-cert\-extensions\~\fIextensions\fP
Specifies the certificate extensions for generating a certificate signing
request (CSR) or self\-signed certificate, in the form
\fB<name>=[critical,]<value(s)>(;<name>=[critical,]<value(s)>)*[;]\fP
with extension names and values recognized by OpenSSL.
A certificate used to authenticate at a KMIP server usually needs the
\fBTLS Web client authentication\fP extended\-key\-usage certificate extension.
Additionally, the \fBCommon Name\fP field or the \fBSubject Alternate Name\fP
extension must match the host name (or IP address) of the client system. If no
extended\-key\-usage extension is specified, then a \fBTLS Web client
authentication\fP extension ('extendedKeyUsage=clientAuth') is automatically
added. If no \fBSubject Alternate Name\fP extension is specified, then a
\fBSubject  Alternate Name\fP extension with the system's host name
(subjectAltName=DNS:hostname) is automatically added.
.TP
.BR \-N ", " \-\-renew\-cert\~\fIcert\-pem\-file\fP
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.
.TP
.BR \-n ", " \-\-csr\-new\-header
Adds the word \fBNEW\fP to the PEM file header and footer lines on the
certificate signing request. Some software and some CAs require this marking.
.TP
.BR \-d ", " \-\-cert\-validity\-days\~\fIdays\fP
Specifies the number of days the self\-signed certificate is valid. The default
is 30 days.
.TP
.BR \-D ", " \-\-cert\-digest\~\fIdigest\fP
Specifies the digest algorithm to use when generating a certificate signing
request (CSR) or self\-signed certificate. The default is determined by OpenSSL.
.TP
.BR \-P ", " \-\-cert\-rsa\-pss
Uses the \fBRSA\-PSS\fP 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.
.TP
.BR \-r ", " \-\-client\-cert\~\fIcert\-pem\-file\fP
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.
.TP
.BR \-S ", " \-\-kmip\-server\~\fIserver\fP
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 \fBhttps://\fP,
followed by the hostname or IP address of the KMIP server, an optional port
number, and an URI (for example \fB/kmip\fP).
.TP
.BR \-p ", " \-\-profile\~\fIprofile\-name\fP
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 \fB/etc/zkey/kmip/profiles\fP. You can set the location of the
profiles by using the environment variable \fBZKEY_KMIP_PROFILES\fP.
.TP
.BR \-b ", " \-\-tls\-ca\-bundle\~\fIca\-bundle\fP
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
\fBc_rehash\fP utility of OpenSSL. Default is to use the system CA certificates.
.TP
.BR \-\-tls\-pin\-server\-pubkey
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.
.TP
.BR \-\-tls\-trust\-server\-cert
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 \fB\-\-tls\-pin\-server\-pubkey\fP option when you are using
self\-signed KMIP server certificates.
.TP
.BR \-\-tls\-dont\-verify\-server\-cert
Do not verify the authenticity of the certificate of the KMIP server. For
self\-signed KMIP server certificates, this is the default. Use the
\fB\-\-tls\-pin\-server\-cert\fP 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.
.TP
.BR \-\-tls\-verify\-hostname
Verifies that the KMIP server certificate’s \fBCommon Name\fP field or a
\fBSubject Alternate Name\fP field matches the hostname that is used to connect
to the KMIP server.
.TP
.BR \-w ", " \-\-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 at a later time.
.TP
.BR \-B ", " \-\-label\~\fIlabel\fP
Specifies an optional human\-readable identifier of the wrapping key stored in
the \fBName\fP KMIP attribute of the key. KMIP names must usually be unique
within the KMIP server.
.
.SS "Options for the zkey generate command"
.
.TP
.BR \-B ", " \-\-label\~\fIlabel[:label]\fP
Specifies an optional human\-readable identifier of the key or keys stored in
the \fBName\fP 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.
.
.SS "Options for the zkey remove command"
.
.TP
.BR \-s ", " \-\-state\~\fIstate\fP
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 \fBDEACTIVATED\fP, \fBCOMPROMISED\fP, \fBDESTROYED\fP, and
\fBDESTROYED\-COMPROMISED\fP. 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.
.
.SS "Options for the zkey kms import command"
.
.TP
.BR \-K ", " \-\-key\-type\~\fItype\fP
Specifies the type of the key to import. Possible values are \fBCCA\-AESDATA\fP,
\fBCCA\-AESCIPHER\fP, and \fBEP11\-AES\fP. The key type must be matching to the
type of APQNs associated with the KMIP plugin. When cryptographic adapters in
\fBCCA\fP coprocessor mode are associated with the KMIP plugin, secure keys of
type \fBCCA\-AESDATA\fP, and \fBCCA\-AESCIPHER\fP are supported. When
cryptographic adapters in \fBEP11\fP coprocessor mode are associated with the
KMIP plugin, secure keys of type \fBEP11\-AES\fP are supported.
When this option is omitted, the default is \fBCCA\-AESDATA\fP when
cryptographic adapters in \fBCCA\fP coprocessor mode are associated with the
KMIP plugin, and \fBEP11\-AES\fP when cryptographic adapters in \fBEP11\fP
coprocessor mode are associated with the KMIP plugin.
.
.SH KMIP PLUGIN PROFILES
This section describes the \fBKMIP plugin profiles\fP. 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.
.PP
\fBNote:\fP KMIP plugin profiles must not be confused with the \fP KMIP
profiles\fP as defined by the KMIP standard.
.PP
A KMIP plugin profile is selected when configuring the connection to the KMIP
server. Either, a profile name is explicitly specified using the
\fB\-\-profile\fP option of the \fBzky kms configure\fP command together with
the \fB\-\-kmip\-server\fP option, or a profile is automatically selected based
on the KMIP server information string that the KMIP server returned with the
KMIP \fBQUERY\fP command response. If none of the available profiles match to
the KMIP server information string, the default profile is used.
.PP
KMIP plugin profiles are text files with a naming scheme like
\fBproduct\-name.profile\fP and are located in directory
\fB/etc/zkey/kmip/profiles\fP. The profiles location can be overridden with
environment variable \fBZKEY_KMIP_PROFILES\fP. At least the default profile
must exist, i.e. in file \fBdefault.profile\fP. 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
\fBhttps://github.com/ibm\-s390\-linux/s390\-tools\fP and supply a profile for
your KMIP server.
.PP
The following parameters and settings are specified in a KMIP plugin profile:
.RS 2
.IP "\(bu" 2
A \fBregular expression\fP 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.
.IP "\(bu" 2
The \fBKMIP protocol version\fP to use. This can be either a specific KMIP
protocol version like \fBmajor.minor\fP or \fBAUTO\fP. When AUTO is specified,
the KMIP protocol version supported by the KMIP server is automatically discoved
using the \fBDISCOVER VERSIONS\fP KMIP request.
.IP "\(bu" 2
The \fBtransport method\fP. Possible values are \fBTSL\fP or \fBHTTPS\fP.
A transport method of HTTPS can also be selected by specifying an URL beginnig
with \fBhttps://\fP with the \fB\-\-kmip\-server\fP option with the
\fBzkey kms configure\fP command, even if the profile used specifies TLS.
.IP "\(bu" 2
The \fB encoding method\fP for the KMIP protocol. Possible values are
\fBTTLV\fP, \fBJSON\fP, or \fBXML\fP. JSON and XML encoding are only posisble
with the HTTPS transport method.
.IP "\(bu" 2
The default \fBURI\fP used for the HTTPS transport method, e.g. \fB/kmip\fP.
The URI can be overridden with the \fB\-\-kmip\-server\fP option with the
\fBzkey kms configure\fP command. This setting is ignored if the transport
method is not HTTPS.
.IP "\(bu" 2
The \fBauthentication scheme\fP. Currently only \fBTLS client authentication\fP
is supported.
.IP "\(bu" 2
The \fBkey wrapping algorithm\fP for retrieving keys from the KMIP server.
Currently only \fBRSA\fP is supported.
.IP "\(bu" 2
The \fBRSA modulus size\fP of the RSA wrapping key in bits. Possible values are
512, 1024, 2048, and 4096 bits.
.IP "\(bu" 2
The \fBkey format\fP used to register the public wrapping key with the KMIP
server. Possible values are \fBPKCS #1\fP, \fBPKCS #8\fP, and
\fBTransparent Public Key\fP.
.IP "\(bu" 2
The \fBpadding method\fP used with RSA key wrapping. Possible values are
\fBPKCS #1.5\fP or \fBOAEP\fP.
.IP "\(bu" 2
The \fBhashing algorithm\fP 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 \fBSHA\-1\fP
and \fBSHA\-256\fP.
.IP "\(bu" 2
Specifies if the KMIP server supports the KMIP \fBLink\fP attribute. If
\fBTRUE\fP, the KMIP plugin uses KMIP \fBLink\fP attributes to link the 2 keys
of an XTS key together. Otherwise, KMIP custom/vendor attributes with a zkey
specific name are used.
.IP "\(bu" 2
Specifies if the KMIP server supports the KMIP \fBDescription\fP attribute.
If not supported, the KMIP plugin uses the KMIP \fBComment\fP attribute (if
supported), or a KMIP custom/vendor attribute with a zkey specific name.
.IP "\(bu" 2
Specifies if the KMIP server supports the KMIP \fBComment\fP attribute.
If not supported, the KMIP plugin uses a KMIP custom/vendor attribute with a
zkey specific name instead.
.IP "\(bu" 2
Specifies the \fBcustom/vendor attribute scheme\fP for KMIP servers supporting
the KMIP protocol version 2.0 or higher. Possible values are \fBv1\-style\fP and
\fBv2\-style\fP. For \fBv1\-style\fP, the attribute's \fBVendor Identifier\fP is
set to \fBx\fP, and \fBAttribute Name\fP is set to \fBzkey\-<something>\fP.
This corresponds to the KMIP custom attribute style of the KMIP protocol version
1.0 - 1.4. For \fBv2\-style\fP, the attribute's \fBVendor Identifier\fP is
set to \fBzkey\fP, and \fBAttribute Name\fP is set to \fB<something>\fP.
.IP "\(bu" 2
Specifies if the KMIP server supports the KMIP \fBSensitive\fP attribute.
If \fBTRUE\fP, all keys are generated with \fBSensitive=True\fP to prevent the
key from being retrieved in clear from the KMIP server.
.IP "\(bu" 2
Specifies if the KMIP server supports the KMIP \fBAlways Sensitive\fP attribute.
If \fBTRUE\fP, all keys retrieved from the KMIP server are checked to have
\fBAlways Sensitive=True\fP to ensure that the key was never able to be
retrieved in clear from the KMIP server.
.RE
.
.
.
.SH EXAMPLES
.TP
.B zkey kms plugins
Lists available key manamgement system plugins.
.TP
.B zkey kms bind KMIP
Binds the KMIP plugin to the current secure key repository.
.TP
.B zkey kms configure \-\-apqns 03.004c
Configures the APQN '03.004c' to be associated with the KMIP plugin.
.TP
.B zkey kms configure \-\-gen\-identity\-key RSA:4096
Generates an RSA identity key with a modulus size of 4096 bits.
.TP
.B zkey kms configure \-\-gen\-identity\-key ECC:secp521r1
Generates an ECC identity key with ellitic curve secp521r1.
.TP
.B zkey kms configure \-\-gen\-csr csr.pem \-\-cert\-subject \(dqCN=my.zkey.client;OU=Example;C=US\(dq
Generates a certificate signing request with the identity key and the specified
subject name and stores it in file 'csr.pem'.
.TP
.B zkey kms configure \-\-gen\-csr csr.pem \-\-renew\-cert cert.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'.
.TP
.B zkey kms configure \-\-gen\-self\-signed\-cert cert.pem \-\-cert\-subject \(dqCN=my.zkey.client;OU=Example;C=US\(dq \-\-cert\-validity\-days 50
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'.
.TP
.B zkey kms configure \-\-gen\-self\-signed\-cert cert.pem \-\-cert\-subject \(dqCN=my.zkey.client;OU=Example;C=US\(dq \-\-cert\-extensions \(dqkeyUsage=critical,digitalSignature,keyAgreement\(dq
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'.
.TP
.B zkey kms configure \-\-client\-cert cert.pem
Use the CA\-signed client certificate in file 'cert.pem' with the KMIP plugin.
.TP
.B zkey kms configure \-\-kmip\-server my.kmip.server
Configures the connection to the KMIP server on 'my.kmip.server'.
.TP
.B zkey kms configure \-\-kmip\-server https://my.kmip.server/kmip
Configures the connection to the KMIP server on 'my.kmip.server' using HTTPS
transport.
.TP
.B zkey kms configure \-\-kmip\-server my.kmip.server \-\-profile ABC
Configures the connection to the KMIP server on 'my.kmip.server' and use the
KMIP plugin profile 'ABC'.
.TP
.B zkey kms configure \-\-kmip\-server my.kmip.server \-\-tls\-pin\-server\-pubkey \-\-tls\-verify\-hostname
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.
.TP
.B zkey kms info
Displays information about the KMIP plugin and its configuration.
.TP
.B zkey kms reencipher \-\-staged
Reenciphers the KMIP Plugin's identity key with a new master key in staged
mode
.TP
.B zkey generate \-\-name seckey \-\-volumes /dev/dasdc1:encvol \-\-label TEST
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'.
.TP
.B zkey generate \-\-name seckey \-\-xts \-\-volumes /dev/dasdc1:encvol \-\-volume\-type luks2 \-\-label TEST1:TEST2
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.
.TP
.B zkey remove \-\-name seckey \-\-state DEACTIVATED
Removes secure key 'seckey' from the repository and sets the state of the key
to 'DEACTIVATED' in the KMIP server.
.TP
.B zkey kms list
Displays eligible secure keys managed by KMIP server.
.TP
.B zkey kms list \-\-label \(dq*LUKS2*\(dq
Displays eligible secure keys managed by the KMIP server where the label name
in the KMIP server contains the word 'LUKS2'.
.TP
.B zkey kms import \-\-name seckey
Imports the secure key managed by the KMIP server with a zkey name of 'seckey'.
.TP
.B zkey kms import \-\-volume\-type LUKS2
Imports secure keys managed by the KMIP server that are associated with volumes
of volume type LUKS2.
.TP
.B zkey kms refresh \-\-name \(dqsec*\(dq
Refreshes secure keys from the KMIP server where the name starts with 'sec'.
.TP
.B zkey kms refresh \-\-name seckey \-\-refresh\-properties
Refreshes the secure key with the name 'seckey' from the KMIP server and also
refreshes the key properties.
.
.
.
.SH ENVIRONMENT
.TP
.BR ZKEY_KMIP_PROFILES
If
.B $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 \fB/etc/zkey/kmip/profiles\fP.