ZKEY-EKMFWEB(1)

NAME
zkey-ekmfweb - Key management system plugin for EKMF Web (IBM Enterprise Key Management Foundation - Web Edition)

DESCRIPTION
The zkey-ekmfweb.so library is a key management system plugin for zkey and provides an interface to EKMF Web (IBM Enterprise Key Management Foundation - Web Edition). It allows to integrate the external key management system EKMF Web into zkey.

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.

EKMF Web supports secure keys of type CCA-AESCIPHER, and requires one or multiple IBM cryptographic adapters in CCA coprocessor mode of version 6 or later, e.g. a CEX6C.

  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.

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

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

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

  Configure the EKMF Web key management system plugin
Use the zkey kms configure command to configure or re-configure the EKMF Web plugin. Use command zkey kms configure --help to display the possible command line options to perform the configuration.

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

The following settings must be configured:

    •   The APQNs 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 --apqns option to specify the APQNs to associate with the EKMF Web plugin.

    •   The connection to the EKMF Web server. The EKMF Web plugin communicates with EKMF Web via RESTful web services over HTTPS (Hypertext Transfer Protocol Secure). Use option --ekmfweb-url to specify the URL of the EKMF Web server. The URL should start with 'https://', 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 zkey kms configure --help to display the possible command line options.

    •   The EKMF Web settings, 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 --refresh-settings to refresh the settings, when they have changed in EKMF Web.

    •   The secure identity key 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 --gen-identity-key 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.

    •   The registration certificate to register the zkey client with EKMF Web. The registration certificate is an X.509 certificate generated with the secure identity key. Use option --gen-csr to generate a certificate signing request (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 --gen-self-signed-cert to generate a self signed certificate with the identity key for the EKMF Web plugin. Use options --cert-subject and --cert-extensions to specify the certificate subject name and extensions (if any). To renew an existing certificate, use option --renew-cert. The subject name and extensions are then read from the certificate that is to be renewed.

    •   Register the zkey client with EKMF Web. Use option --register to register the zkey client using the registration certificate 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 --label-tags to specify the label tags for creating the identity key in EKMF Web. Use command zkey kms info to find out which label tags the identity key template uses.

  Re-encipher the secure identity key
Use the zkey kms reencipher 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 APKA master key of the CCA cryptographic adapter changes.

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

Note: The zkey kms reencipher command does not 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 zkey reencipher command to re-encipher those secure keys.

  Generating secure AES keys with EKMF Web
Use the zkey generate 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 zkey generate command always generates the keys in EKMF Web, except when the --local option is specified.

Keys generated in EKMF Web are always of type CCA-AESCIPHER. The cryptographic size of the keys depend on the underlying EKMF Web template. Use zkey kms info to display the names of the key templates configured. If option --key-bits is specified, it must match the key size in the template.

You may need to use option --label-tags to specify the label tags for creating keys in EKMF Web. Use command zkey kms info to find out which label tags the configured key template uses.

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 --description, --volumes, --volume-type, or the --sector-size options. This associated information is also stored in EKMF Web with the key.

  Remove secure keys bound to EKMF Web from the key repository
Use the zkey remove 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 --state 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.

  Change secure keys bound to EKMF Web
Use the zkey change 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.

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 zkey kms configure command with the --apqns option. This also changes the APQN associations of all secure keys in the secure key repository, that are bound to the EKMF Web plugin.

  Rename secure keys bound to EKMF Web
Use the zkey rename 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.

  List secure keys managed by EKMF Web
Use the zkey kms list 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 zkey for the details on these filter options.

Use option --states 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 ACTIVE state are displayed.

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 --all 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.

  Import secure keys managed by EKMF Web into the repository
Use the zkey kms import 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 zkey for the details on these filter options.

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.

  Refresh secure keys bound to EKMF Web
Use the zkey kms refresh 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 --refresh-properties 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 zkey for the details on the zkey kms refresh command.

The zkey kms refresh command can also help if the secure keys have not been re-enciphered properly after a CCA master key change, and thus became invalid. By refreshing the keys using the zkey kms refresh 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 zkey reencipher command for keys that are bound to EKMF Web.

OPTIONS
This section describes the EKMF Web plugin specific options of the zkey commands. Refer to the zkey man page for the remaining, non EKMF Web plugin specific options.

  Options for the zkey kms configure command

-u, --ekmfweb-url url
    Specifies the URL of the EKMF Web server. The URL should start with https://, and may contain a port number separated by a colon. If no port number is specified, 443 is used for HTTPS.

-b, --tls-ca-bundle ca-bundle
    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 c_rehash utility. Default are the system CA certificates.

--tls-client-cert pem-file
    Specifies the PEM file containing the client's TLS certificate for use with TLS client authentication.

--tls-client-key pem-file
    Specifies the PEM file containing the client's private key for use with TLS client authentication.

--tls-client-key-passphrase passphrase
    If the PEM file is passphrase protected, this option specifies the passphrase to unlock the PEM file that is specified with option --tls-client-key.

--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.

--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 --tls-pin-server-pubkey with self signed EKMF Web server certificates.

--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 --tls-pin-server-cert to ensure the self signed certificate's authenticity explicitly. CA signed EKMF Web server certificates are verified by default. This option disables the verification.

--tls-verify-hostname
     Verify that the EKMF Web server certificate's Common Name field or a Subject Alternate Name field matches the host name used to connect to the EKMF Web server.

-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.

-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.

-c, --gen-csr csr-pem-file
    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.

-C, --gen-self-signed-cert cert-pem-file
    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.

-s, --cert-subject subject-rdns
    Specifies the subject name for generating a certificate signing request (CSR) or self signed certificate, in the form <type>=<value>(;<type>=<value>)*[;] with types recognized by OpenSSL.

-s, --cert-extensions extensions
    Specifies the certificate extensions for generating a certificate signing request (CSR) or self signed certificate, in the form <name>=[critical,]<value(s)>(;<name>=[critical,]<value(s)>)*[;] with extension names and values recognized by OpenSSL.

-N, --renew-cert cert-pem-file
    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.

-n, --csr-new-header
    Adds the word NEW to the PEM file header and footer lines on the certificate signing request. Some software and some CAs need this.

-d, --cert-validity-days days
    Specifies the number of days to certify the self signed certificate. The default is 30 days.

-D, --cert-digest digest
    Specifies the digest algorithm to use when generating a certificate signing request or self signed certificate. The default is determined by OpenSSL.

-r, --register cert-file
    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 .pem, .crt, .cert, .cer, and .der (i.e. either base64 or DER encoded). If you want to register a self signed certificate that you are about to generate using option --gen-self-signed-cert, then specify the same certificate file name here, and the generated certificate is registered right away.

-T, --label-tags label-tags
    Specifies the label tags for generating the identity key in EKMF Web when registering the zkey client, in the form <tag>=<value>(,<tag>=<value>)*[,] with tags as defined by the key template. Use the zkey kms info command to display the key templates used by zkey. For registration, the template for identity keys is used.

  Options for the zkey generate command

-T, --label-tags label-tags
    Specifies the label tags for generating a secure key in EKMF Web, in the form <tag>=<value>(,<tag>=<value>)*[,] with tags as defined by the key template. Use the zkey kms info command to display the key templates used by zkey. For XTS type keys the two templates for XTS-Key1 and XTS-Key2 are used. For non-XTS type keys, the template for Non-XTS keys is used.

  Options for the zkey remove command

-s, --state state
    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 DEACTIVATED, COMPROMISED, DESTROYED, and DESTROYED-COMPROMISED. 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.

  Options for the zkey kms list command

-s, --states states
    Specifies the states of the keys that are to be listed. Multiple states can be separated by comma. Possible states are PRE-ACTIVATION, ACTIVE, DEACTIVATED, COMPROMISED, DESTROYED, and DESTROYED-COMPROMISED. If this option is not specified, only keys in state ACTIVE are listed.

-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.

EXAMPLES

zkey kms plugins
    Lists available key manamgement system plugins.

zkey kms bind EKMFWeb
    Binds the EKMF Web plugin to the current secure key repository.

zkey kms configure --apqns 03.004c
    Configures the APQN '03.004c' to be associated with the EKMF Web plugin.

zkey kms configure --ekmfweb-url https://my.ekmfweb.server
    Configures the connection to the EKMF Web server on 'my.ekmfweb.server'.

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 nmae to match the server's Common Name in the certificate.

zkey kms configure --gen-csr csr.pem --cert-subject "CN=my.zkey.client;OU=Example;C=US"
    Generates a certificate signing request with the identity key and the specified subject name and stores it in file 'csr.pem'.

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'.

zkey kms configure --gen-self-signed-cert cert.pem --cert-subject "CN=my.zkey.client;OU=Example;C=US" --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'.

zkey kms configure --gen-self-signed-cert cert.pem --cert-subject "CN=my.zkey.client;OU=Example;C=US" --cert-extensions "keyUsage=critical,digitalSignature,keyAgreement"
    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'.

zkey kms configure --register cert.pem
    Registers the zkey client with EKMF Web using the certifcate in file 'cert.pem'.

zkey kms configure --register cert.pem --label-tags "ENV=TEST,APP=LINUX"
    Registers the zkey client with EKMF Web using the certifcate in file 'cert.pem' and the label tags 'ENV=TEST' and 'APP=LINUX' for the identity key.

zkey kms info
    Displays information about the EKMF Web plugin and its configuration.

zkey kms reencipher --staged
    Re-enciphers the EKMF Plugin's identity key with a new CCA master key in staged mode

zkey generate --name seckey --volumes /dev/dasdc1:encvol --label-tags "ENV=TEST,APP=LINUX"
    Generates a secure AES key in EKMF Web using the label tags 'ENV=TEST' and and associates it with block device '/dev/dasdc1' and device-mapper name

zkey generate --name seckey --xts --volumes /dev/dasdc1:encvol --volume-type luks2 --label-tags "ENV=TEST,APP=LINUX"
    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.

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.

zkey kms list
    Displays eligible secure keys managed by EKMF Web which this zkey client is allowed to use and are in state 'ACTIVE'

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'

zkey kms list --all
    Displays eligible secure keys managed by EKMF Web, regardless if this zkey client is allowed to use it or not.

zkey kms list --label "*LUKS2*"
    Displays eligible secure keys managed by EKMF Web where the label name in EKMF Web contains the work 'LUKS2'.

zkey kms import --name seckey
    Imports the secure key managed by EKMF Web with a zkey name of 'seckey'.

zkey kms import --volume-type LUKS2
    Imports secure keys managed by EKMF Web that are associated with volumes of volume type LUKS2.

zkey kms refresh --name "sec*"
    Refreshes secure keys from EKMF Web where the name starts with 'sec'.

zkey kms refresh --name seckey --refresh-properties
    Refreshes the secure key with the name 'seckey' from EKMF Web and also refreshs the key properties.