s390-tools/zkey/ekmfweb/zkey-ekmfweb.1

.\" Copyright IBM Corp. 2020
.\" 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\-EKMFWEB 1 "July 2020" "s390-tools"
.SH NAME
zkey\-ekmfweb \- Key management system plugin for EKMF Web (IBM Enterprise Key
Management Foundation \- Web Edition)
.
.
.
.SH DESCRIPTION
The \fBzkey\-ekmfweb.so\fP library is a key management system plugin for
\fBzkey\fP and provides an interface to \fBEKMF Web\fP (IBM Enterprise Key
Management Foundation \- Web Edition). It allows to integrate the external key
management system EKMF Web into zkey.
.PP
Secure AES keys can be generated in EKMF Web and are then imported into the zkey
secure key repository. The keys can be used to encrypt volumes, the same way
as with secure AES keys generated by zkey locally.
.PP
EKMF Web supports secure keys of type \fBCCA\-AESCIPHER\fP, and requires one or
multiple \fBIBM cryptographic adapters in CCA coprocessor mode\fP of version 6
or later, e.g. a CEX6C.
.
.SS "Bind the zkey secure key repository to EKMF Web"
.
To use EKMF Web with zkey, the zkey secure key repository must first be bound to
the EKMF Web key management system plugin.
.PP
Use the \fBzkey kms plugins\fP command to list available key management system
plugins. The EKMF Web plugin appears as plugin \fBEKMFWeb\fP in the list of
available plugins. If it does not appear, check if it is configured properly in
configuration file \fB/etc/zkey/kms\-plugins.conf\fP. Refer to the \fBzkey\fP
man page for details about this configuration file.
.PP
Use the \fBzkey kms bind EKMFWeb\fP command to bind the EKMF Web key management
system plugin to the zkey repository. You must then configure the EKMF Web
plugin with command \fBzkey kms configure\fP before it can be used.
.
.SS "Display information about the EKMF Web key management system plugin"
.
Use the \fBzkey kms info\fP command to display information about the EKMF Web
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 EKMF Web plugin. Use the \fBzkey kms
configure\fP to do so.
.
.SS "Configure the EKMF Web key management system plugin"
.
Use the \fBzkey kms configure\fP command to configure or re\-configure the
EKMF Web plugin. Use command \fBzkey kms configure \-\-help\fP to display the
possible command line options to perform the configuration.
.PP
Configuring the EKMF Web 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 \fBAPQNs\fP associated with the EKMF Web key management system plugin. These
APQNs are used by the EKMF Web plugin to generate internally used secure keys
(i.e. the identity key), as well as to import secure AES keys from EKMF Web into
the zkey repository, enciphered with the current CCA master key. Secure keys
imported from EKMF Web will automatically be associated with the APQNs
associated with the EKMF Web plugin. Use the \fB\-\-apqns\fP option to specify
the APQNs to associate with the EKMF Web plugin.
.
.IP "\(bu" 2
The \fBconnection to the EKMF Web server\fP. The EKMF Web plugin communicates
with EKMF Web via RESTful web services over HTTPS (Hypertext Transfer Protocol
Secure). Use option \fB\-\-ekmfweb\-url\fP to specify the URL of the EKMF Web
server. The URL should start with \fB'https://'\fP, and may contain a port
number separated by a colon. If no port number is specified, 443 is used for
HTTPS. Additional TLS (Transport Layer Security) specific options can be
specified to control the behavior of the TLS protocol and the validation of the
EKMF Web server's certificate. Use command \fBzkey kms configure \-\-help\fP to
display the possible command line options.
.
.IP "\(bu" 2
The \fBEKMF Web settings\fP, such as the EKMF Web server's public key and the
key templates used by EKMF Web to generate keys. These settings are
automatically retrieved from EKMF Web, once the connection to the EKMF Web
server has been configured. Use option \fB\-\-refresh\-settings\fP to refresh
the settings, when they have changed in EKMF Web.
.
.IP "\(bu" 2
The secure \fBidentity key\fP used to identify the zkey client with EKMF Web,
and to cryptographically sign requests sent to EKMF Web. The identity key
is a secure key, and is automatically generated once the connection to the
EKMF Web server has been configured. Use option \fB\-\-gen\-identity\-key\fP to
re-generate the identity key, if needed. You must re-generate a
registration certificate with the newly generated identity key and re-register
this zkey client with the EKMF Web server.
.
.IP "\(bu" 2
The \fBregistration certificate\fP to register the zkey client with EKMF Web.
The registration certificate is an X.509 certificate generated with the secure
identity key. Use option \fB\-\-gen\-csr\fP to generate a \fBcertificate signing
request\fP (CSR) with the identity key. You pass this CSR to a certificate
authority (CA) to have it issue a CA signed certificate for the EKMF Web
plugin. Alternatively, use option \fB\-\-gen\-self\-signed\-cert\fP to generate
a \fBself signed certificate\fP with the identity key for the EKMF Web plugin.
Use options \fB\-\-cert\-subject\fP and \fB\-\-cert\-extensions\fP to specify
the certificate subject name and extensions (if any). To renew an existing
certificate, use option \fB\-\-renew\-cert\fP. The subject name and extensions
are then read from the certificate that is to be renewed.
.
.IP "\(bu" 2
\fBRegister\fP the zkey client with EKMF Web. Use option \fB\-\-register\fP to
register the zkey client using the \fBregistration certificate\fP from the
previous step. An identity key is generated in EKMF Web using the public
key from the certificate. You may also need to use option
\fB\-\-label\-tags\fP to specify the label tags for creating the identity key
in EKMF Web. Use command \fBzkey kms info\fP to find out which label tags the
identity key template uses.
.RE
.
.SS "Re-encipher the secure identity key"
.
Use the \fBzkey kms reencipher\fP command to re-encipher the secure identity
key of the EKMF Web plugin with a new master key.
The secure identity key must be re-enciphered when the \fBAPKA master key\fP
of the CCA cryptographic adapter changes.
.PP
See the man page of \fBzkey\fP for a description of the the \fBzkey kms
reencipher\fP command.
.PP
\fBNote:\fP The \fBzkey kms reencipher\fP command does \fBnot\fP re-encipher
secure keys that have been generated by or have been imported from EKMF Web and
are now stored in the secure key repository. Use the regular \fBzkey
reencipher\fP command to re-encipher those secure keys.
.
.SS "Generating secure AES keys with EKMF Web"
.
Use the \fBzkey generate\fP command to generate secure AES keys in EKMF Web and
import the newly generated key into the secure key repository. When the zkey
repository is bound to the EKMF Web plugin, then the \fBzkey generate\fP command
always generates the keys in EKMF Web, except when the \fB\-\-local\fP
option is specified.
.PP
Keys generated in EKMF Web are always of type \fBCCA\-AESCIPHER\fP. The
cryptographic size of the keys depend on the underlying EKMF Web template.
Use \fBzkey kms info\fP to display the names of the key templates configured.
If option \fB\-\-key\-bits\fP is specified, it must match the key size in the
template.
.PP
You may need to use option \fB\-\-label\-tags\fP to specify the label tags
for creating keys in EKMF Web. Use command \fBzkey kms info\fP to find out
which label tags the configured key template uses.
.PP
Keys generated with EKMF Web are bound to EKMF Web, and also inherit the APQN
association from the EKMF Web plugin. You cannot associate different APQNs to
a key that is bound to EKMF Web. Other additional information can be associated
with a secure key as usual, using the \fB\-\-description\fP, \fB\-\-volumes\fP,
\fB\-\-volume\-type\fP, or the \fB\-\-sector\-size\fP options. This associated
information is also stored in EKMF Web with the key.
.
.SS "Remove secure keys bound to EKMF Web from the key repository"
.
Use the \fBzkey remove\fP command to remove an existing secure key from the
secure key repository. If the key is bound to EKMF Web, then you can also
change the state of the key in EKMF Web, while removing it. Use option
\fB\-\-state\fP to specify the new state of the key in EKMF Web. If no state is
specified, the key remains unchanged in EKMF Web, but is removed from the local
secure key repository only.
.
.SS "Change secure keys bound to EKMF Web"
.
Use the \fBzkey change\fP command to change the description, the associated
volumes, the sector size, and the volume type of a secure key contained in the
secure key repository. If the key is bound to EKMF Web, then the changed
information is also updated for the key in EKMF Web.
.PP
You cannot change the associated cryptographic adapters (APQNs) of a key that
is bound to EKMF Web, because it inherits the APQN association from the EKMF
Web plugin. To change the APQNs associated with the EKMF Web plugin, use the
\fBzkey kms configure\fP command with the \fB--apqns\fP option. This also
changes the APQN associations of all secure keys in the secure key repository,
that are bound to the EKMF Web plugin.
.
.SS "Rename secure keys bound to EKMF Web"
.
Use the \fBzkey rename\fP command to rename an existing secure key in the
secure key repository. If the key is bound to EKMF Web, then the new name
is also updated for the key in EKMF Web. Note that the key label as it
is known in EKMF Web cannot be changed. Only the associated zkey name is
updated.
.
.SS "List secure keys managed by EKMF Web"
.
Use the \fBzkey kms list\fP command to display eligible secure keys managed by
EKMF Web. 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
Use option \fB\-\-states\fP to filter the list by the key state in EKMF Web.
You can specify multiple states, separated by comma. If this option is omitted,
then only keys in \fBACTIVE\fP state are displayed.
.PP
By default, only keys are displayed, which this zkey client is allowed to use.
Only keys where the export control options include the identity key of this zkey
client as allowed exporting key can be used by this zkey client.
Specify option \fB\-\-all\fP to also list keys that this zkey client is
not allowed to use. The EKMF Web operator can change the export control options
of a key to allow a certain zkey identity key to export the key.
.
.SS "Import secure keys managed by EKMF Web into the repository"
.
Use the \fBzkey kms import\fP command to import secure keys managed by EKMF Web
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
Only keys are imported, which this zkey client is allowed to use. Only keys
where the export control options include the identity key of this zkey
client as allowed exporting key can be used by this zkey client. The EKMF Web
operator can change the export control options of a key, to allow a certain
zkey identity key to export the key.
.
.SS "Refresh secure keys bound to EKMF Web"
.
Use the \fBzkey kms refresh\fP command to refresh secure keys that are bound to
EKMF Web. 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
re-importing it from EKMF Web. Use option \fB\-\-refresh\-properties\fP to also
update the associated information, such as the textual description, associated
volumes, volume type, and sector size, with the information stored with the key
in EKMF Web. 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 re-enciphered properly after a CCA master key change, and thus became
invalid. By refreshing the keys using the \fBzkey kms refresh\fP command, the
secure key is re-imported under the current CCA master key. So this command
could also be used as an alternative to the \fBzkey reencipher\fP command for
keys that are bound to EKMF Web.
.
.
.
.SH OPTIONS
This section describes the EKMF Web plugin specific options of the \fBzkey\fP
commands. Refer to the \fBzkey\fP man page for the remaining, non EKMF Web
plugin specific options.
.
.SS "Options for the zkey kms configure command"
.TP
.BR \-u ", " \-\-ekmfweb\-url\~\fIurl\fP
Specifies the URL of the EKMF Web server. The URL should start with
\fBhttps://\fP, and may contain a port number separated by a colon. If no
port number is specified, 443 is used for HTTPS.
.TP
.BR \-b ", " \-\-tls\-ca\-bundle\~\fIca\-bundle\fP
Specifies the CA bundle PEM file or directory containing the CA certificates
used to verify the EKMF Web server certificate during TLS handshake. If this
specifies a directory path, then this directory must have been prepared
with OpenSSL's \fBc_rehash\fP utility. Default are the system CA certificates.
.TP
.BR \-\-tls\-client\-cert\~\fIpem\-file\fP
Specifies the PEM file containing the client's TLS certificate for use with
TLS client authentication.
.TP
.BR \-\-tls\-client\-key\~\fIpem\-file\fP
Specifies the PEM file containing the client's private key for use with TLS
client authentication.
.TP
.BR \-\-tls\-client\-key\-passphrase\~\fIpassphrase\fP
If the PEM file is passphrase protected, this option specifies the passphrase
to unlock the PEM file that is specified with option \fB\-\-tls\-client\-key\fP.
.TP
.BR \-\-tls\-pin\-server\-pubkey
Pin the EKMF Web server's public key to verify on every connection that the
public key of the EKMF Web server's certificate is the same that was used when
the connection to the EKMF Web server was configured. This option can only be
used with CA signed EKMF Web server certificates.
.TP
.BR \-\-tls\-trust\-server\-cert
Trust the EKMF Web server's certificate even if it is a  self signed
certificate, or could not be verified due to other reasons. This option can be
used instead of option \fB\-\-tls\-pin\-server\-pubkey\fP with self signed
EKMF Web server certificates.
.TP
.BR \-\-tls\-dont\-verify\-server\-cert
Do not verify the authenticity of the EKMF Web server's certificate. For self
signed EKMF Web server certificates, this is the default. Use option
\fB\-\-tls\-pin\-server\-cert\fP to ensure the self signed certificate's
authenticity explicitly. CA signed EKMF Web server certificates are verified by
default. This option disables the verification.
.TP
.BR \-\-tls\-verify\-hostname
 Verify that the EKMF Web server certificate's \fBCommon Name\fP field or a
\fBSubject Alternate Name\fP field matches the host name used to connect to the
EKMF Web server.
.TP
.BR \-R ", " \-\-refresh\-settings
Refresh the EKMF Web server settings. This is automatically performed when the
connection to the EKMF Web server is (re-)configured. Use this option when the
settings of the already configured EKMF Web server have changed.
.TP
.BR \-i ", " \-\-gen\-identity\-key
Generate an identity key for the EKMF Web plugin. An identity key is
automatically generated when the EKMF Web server connection has been configured.
Use this option to generate a new identity key. You need to re-generate a
registration certificate with the newly generated identity key, and re-register
this zkey client with the EKMF Web server.
.TP
.BR \-c ", " \-\-gen\-csr\~\fIcsr\-pem\-file\fP
Generate a certificate signing request (CSR) with the identity key and store it
into the specified PEM file. You pass this CSR to a certificate authority (CA)
to have it issue a CA signed certificate for the EKMF Web plugin. You need to
register the certificate with EKMF Web before you can access EKMF Web.
.TP
.BR \-C ", " \-\-gen\-self\-signed\-cert\~\fIcert\-pem\-file\fP
Generate a self signed certificate with the identity key and store it into the
specified PEM file. You need to register the certificate with EKMF Web before
you can access EKMF Web.
.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.
.TP
.BR \-N ", " \-\-renew\-cert\~\fIcert\-pem\-file\fP
Specifies an existing PEM file containing  the certificate to be renewed. The
certificate's subject name and extensions 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 need this.
.TP
.BR \-d ", " \-\-cert\-validity\-days\~\fIdays\fP
Specifies the number of days to certify the self signed certificate. The
default is 30 days.
.TP
.BR \-D ", " \-\-cert\-digest\~\fIdigest\fP
Specifies the digest algorithm to use when generating a certificate signing
request or self signed certificate. The default is determined by OpenSSL.
.TP
.BR \-r ", " \-\-register\~\fIcert\-file\fP
Register the zkey client with EKMF Web by generating an identity key in EKMF
Web using the certificate from the specified file. Supported  certificate files
formats are \fB.pem\fP, \fB.crt\fP, \fB.cert\fP, \fB.cer\fP, and \fB.der\fP
(i.e. either base64 or DER encoded). If you want to register a self signed
certificate that you are about to generate using option
\fB\-\-gen\-self\-signed\-cert\fP, then  specify the same certificate file
name here, and the generated certificate is registered right away.
.TP
.BR \-T ", " \-\-label\-tags\~\fIlabel\-tags\fP
Specifies the label tags for generating the identity key in EKMF Web when
registering the zkey client, in the form
\fB<tag>=<value>(,<tag>=<value>)*[,]\fP with tags as defined by the key
template. Use the \fBzkey kms info\fP command to display the key templates used
by zkey. For registration, the template for identity keys is used.
.
.SS "Options for the zkey generate command"
.
.TP
.BR \-T ", " \-\-label\-tags\~\fIlabel\-tags\fP
Specifies the label tags for generating a secure key in EKMF Web, in the form
\fB<tag>=<value>(,<tag>=<value>)*[,]\fP with tags as defined by the key
template. Use the \fBzkey kms info\fP command to display the key templates used
by zkey. For XTS type keys the two templates for \fBXTS-Key1\fP and
\fBXTS-Key2\fP are used. For non-XTS type keys, the template for \fBNon-XTS\fP
keys is used.
.
.SS "Options for the zkey remove command"
.
.TP
.BR \-s ", " \-\-state\~\fIstate\fP
Specifies the state to which to change the key in EKMF Web, 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 EKMF Web is not changed, but the key is removed from the local secure
key repository only.
.
.SS "Options for the zkey kms list command"
.
.TP
.BR \-s ", " \-\-states\~\fIstates\fP
Specifies the states of the keys that are to be listed. Multiple states can be
separated by comma. Possible states are \fBPRE\-ACTIVATION\fP, \fBACTIVE\fP,
\fBDEACTIVATED\fP, \fBCOMPROMISED\fP, \fBDESTROYED\fP, and
\fBDESTROYED\-COMPROMISED\fP. If this option is not specified, only keys in
state \fBACTIVE\fP are listed.
.TP
.BR \-a ", " \-\-all
List all keys that can be used for volume encryption. If this option is not
specified, then only volume encryption keys that are allowed to be exported by
EKMF Web using the identity key of this zkey client are listed.
.
.
.
.SH EXAMPLES
.TP
.B zkey kms plugins
Lists available key manamgement system plugins.
.TP
.B zkey kms bind EKMFWeb
Binds the EKMF Web 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 EKMF Web plugin.
.TP
.B zkey kms configure \-\-ekmfweb\-url https://my.ekmfweb.server
Configures the connection to the EKMF Web server on 'my.ekmfweb.server'.
.TP
.B zkey kms configure \-\-ekmfweb\-url https://my.ekmfweb.server \-\-tls\-pin\-server\-pubkey \-\-tls\-verify\-hostname
Configures the connection to the EKMF Web server on 'my.ekmfweb.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 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 \-\-register cert.pem
Registers the zkey client with EKMF Web using the certificate in file 'cert.pem'.
.TP
.B zkey kms configure \-\-register cert.pem \-\-label\-tags \(dqENV=TEST,APP=LINUX\(dq
Registers the zkey client with EKMF Web using the certificate in file 'cert.pem'
and the label tags 'ENV=TEST' and 'APP=LINUX' for the identity key.
.TP
.B zkey kms info
Displays information about the EKMF Web plugin and its configuration.
.TP
.B zkey kms reencipher --staged
Re-enciphers the EKMF Plugin's identity key with a new CCA master key in staged
mode
.TP
.B zkey generate \-\-name seckey \-\-volumes /dev/dasdc1:encvol \-\-label\-tags \(dqENV=TEST,APP=LINUX\(dq
Generates a secure AES key in EKMF Web using the label tags 'ENV=TEST' and
'APP=LINUX' 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\-tags \(dqENV=TEST,APP=LINUX\(dq
Generates a secure AES key for the XTS cipher mode in EKMF Web using the label
tags 'ENV=TEST' and 'APP=LINUX' 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 EKMF Web.
.TP
.B zkey kms list
Displays eligible secure keys managed by EKMF Web which this zkey client is
allowed to use and are in state 'ACTIVE'
.TP
.B zkey kms list \-\-states ACTIVE,DEACTIVATED
Displays eligible secure keys managed by EKMF Web which this zkey client is
allowed to use and are in state 'ACTIVE' or 'DEACTIVATED'
.TP
.B zkey kms list \-\-all
Displays eligible secure keys managed by EKMF Web, regardless if this zkey
client is allowed to use it or not.
.TP
.B zkey kms list \-\-label \(dq*LUKS2*\(dq
Displays eligible secure keys managed by EKMF Web where the label name in EKMF
Web contains the word 'LUKS2'.
.TP
.B zkey kms import \-\-name seckey
Imports the secure key managed by EKMF Web with a zkey name of 'seckey'.
.TP
.B zkey kms import \-\-volume\-type LUKS2
Imports secure keys managed by EKMF Web that are associated with volumes of
volume type LUKS2.
.TP
.B zkey kms refresh \-\-name \(dqsec*\(dq
Refreshes secure keys from EKMF Web where the name starts with 'sec'.
.TP
.B zkey kms refresh \-\-name seckey \-\-refresh\-properties
Refreshes the secure key with the name 'seckey' from EKMF Web and also refreshes
the key properties.