mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
07cd9143da
Ensure that all hyphens in command options and examples are escaped properly. Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com> Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>
673 lines
34 KiB
Groff
673 lines
34 KiB
Groff
.\" 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<74>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.
|