ZKEY-EKMFWEB(1)

📦 version 2.44.1, in opensuse-leap 16.0

okay so bestie, welcome to zkey-ekmfweb — yes, that’s ZKEY-EKMFWEB(1), and this is literally the group-chat cheat sheet for the key management system plugin for EKMF Web (IBM Enterprise Key Management Foundation - Web Edition) 💅✨

💖 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 one to integrate the external key management system EKMF Web into zkey. periodt 💅

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

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. it’s giving “do this first or nothing else works” energy 💀

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. lowkey important, bestie 🫶

🦋 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. yep, it’s a vibe check for your config ✨

🌸 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. iykyk, --help is your bestie here 💖

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. choose your own adventure, honestly 🎀

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. secure connection slay 🔐✨
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. refresh queen 👑
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. main character identity energy fr fr 💅
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. certificate lore, but make it cute 🎀
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. register bestie, register 💖

🧚 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. key refresh, but make it secure 🦋

See the man page of zkey for a description of 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. --local is the “actually, do it here” button 👀

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 --keybits is specified, it must match the key size in the template. matching matters, bestie 🎯

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. it’s giving “the key has lore in two places” 🌈

💅 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. local delete vs EKMF Web state change — know the difference 🫶

🔥 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. one config change, many keys affected — iconic ripple effect 👑

🎀 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. rename the zkey name, not the EKMF Web label — important distinction bestie 💅

👑 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. ACTIVE is the default main character state ✨

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. permissions are the real vibe check here 🔐

🍓 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. import only what you’re allowed to import, no cap 🍓

🔄 Refresh secure keys bound to EKMF Web

okay so if you've got secure keys that are bound to EKMF Web and you need to refresh them, zkey kms refresh is literally the moment 💅 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, so it's giving "fresh out of the vault" energy ✨

And here's the tea 🍵 — if you also hit option --refresh-properties, it updates the associated information too, like the textual description, associated volumes, volume type, and sector size, with the information stored with the key in EKMF Web. Head over to the man page of zkey for all the deets on the zkey kms refresh command.

Lowkey a lifesaver moment: 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. slay 🔥

✨ OPTIONS ✨

This section describes the EKMF Web plugin specific options of the zkey commands. For the remaining, non EKMF Web plugin specific options, go check the zkey man page 🫶

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

ngl, that one turns off verification entirely — know what you're doing before you use it 💀

--tls-verify-hostname — This option has no effect anymore, fr fr it's just vibing there 🙈 The (new) default is to always verify that the EKMF Web server certificate's Common Name field or a Subject Alternate Name field matches the hostname that is used to connect to the EKMF Web server. To disable this check, use option --tls-dont-verify-hostname.
--tls-dont-verify-hostname — Disables the verification of the EKMF Web server certificates Common Name field or a Subject Alternate Name field matching the hostname that is used to connect to the EKMF Web server.

⚠️ This is an insecure setting, use with care! Like, the man page literally says that, not me 😭

-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.
-e, --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.
-P, --cert-rsa-pss — Use the RSA-PSS algorithm to sign the certificate signing request or the self signed certificate. This option is only honored when the identity key type is RSA, it is ignored otherwise. This option is only available on systems where the installed version of OpenSSL supports RSA-PSS certificate signing. 💅
-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 file 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 kms configure` command (key transport)

--session-rsa-sign-digest digest — Specifies the digest algorithm to use for signing the key transport request, when the identity key type is RSA. Ignored otherwise. The default is SHA512. This option is only available on systems where the installed version of EKMF Web client library supports RSA digest and PSS signature selection.
--session-rsa-sign-algo algorithm — Specifies the algorithm to use for signing the key transport request, when the identity key type is RSA, ignored otherwise. Supported algorithms are RSA and RSA-PSS. This option is only available on systems where the installed version of EKMF Web client library supports RSA digest and PSS signature selection. 🦋

🪄 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 ✨

Okay bestie, this is the fun part — real commands, real vibes, copy-paste ready. Let's go 💅

zkey kms plugins

Lists available key management system plugins. That's it, that's the whole thing — a little roster of who's available 🫶

zkey kms bind EKMFWeb

Binds the EKMF Web plugin to the current secure key repository. Like, officially making it official between them 💖

zkey kms configure --apqns 03.004c

Configures the APQN 03.004c to be associated with the EKMF Web plugin. One specific APQN, hand-picked, no cap.

zkey kms configure --ekmfweb-url https://my.ekmfweb.server

Configures the connection to the EKMF Web server on my.ekmfweb.server. Say hi to your new server bestie ✨

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 TLS certificate as well as enables verification of the host name to match the server's Common Name in the certificate. Double lock, double slay 🔥

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. Very ✨paperwork era✨ of you.

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. Glow-up arc for your cert 🦋

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. Fifty. Days. Not a day more 🙈

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. Setting boundaries, we love to see it 💅

zkey kms configure --register cert.pem

Registers the zkey client with EKMF Web using the certificate in file cert.pem. Officially on the list 👑

zkey kms configure --register cert.pem --label-tags "ENV=TEST,APP=LINUX"

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. Tagged, organized, thriving 🎀

zkey kms info

Displays information about the EKMF Web plugin and its configuration. The vibe check, basically ⭐

zkey kms reencipher --staged

Re-enciphers the EKMF Plugin's identity key with a new CCA master key in staged mode. Fresh key, staged rollout, main character energy 🔄

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 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. A whole trio: key, 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. XTS + luks2 + tags = the full fit 💜

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. Not a delete-and-ghost, it's a delete-with-receipts 😭

zkey kms list

Displays eligible secure keys managed by EKMF Web which this zkey client is allowed to use and are in state ACTIVE. Just the ones you're allowed to touch, and only the ACTIVE ones 🌸

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. Widening the net, still staying in your lane ✨

zkey kms list --all

Displays eligible secure keys managed by EKMF Web, regardless if this zkey client is allowed to use it or not. Full transparency, permission aside 👀

zkey kms list --label "*LUKS2*"

Displays eligible secure keys managed by EKMF Web where the label name in EKMF Web contains the word LUKS2. Wildcards doing their little magic trick 🪄

zkey kms import --name seckey

Imports the secure key managed by EKMF Web with a zkey name of seckey. Bringing it home 🏠

zkey kms import --volume-type LUKS2

Imports secure keys managed by EKMF Web that are associated with volumes of volume type LUKS2. Batch import, volume-type flavored 🍓

zkey kms refresh --name "sec*"

Refreshes secure keys from EKMF Web where the name starts with sec. Pattern matching said yes 🌈

zkey kms refresh --name seckey --refresh-properties

Refreshes the secure key with the name seckey from EKMF Web and also refreshes the key properties. Key refresh + properties refresh, the ultimate combo 🫶

ngl bestie, that's a lot of examples — but every single one is a real, working invocation, so keep this page bookmarked 💀

And that's the whole page, icon behavior only 💅 This one came from the s390-tools crew, dated July 2020 — go off, thank them, and remember: every flag counts, no skips. periodt. 🎀🦋⭐

📦 where this page comes from

opensuse-leap 16.0: s390-tools 2.44.1-160000.1.1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms