Scroll to navigation

ZKEY(1) General Commands Manual ZKEY(1)

NAME

zkey - Manage secure AES keys

SYNOPSIS

zkey command [secure-key-file] [OPTIONS]

zkey command sub-command [OPTIONS]

zkey --help|-h
zkey --version|-v

DESCRIPTION

Use the zkey tool to generate and manage secure AES keys that are enciphered with a master key of an IBM cryptographic adapter in CCA or EP11 coprocessor mode, dependent on the key type. You can also use the zkey tool to validate and re-encipher secure AES keys.

The secure keys can either be stored in a file in the file system, or in the secure key repository. The default location of the secure key repository is /etc/zkey/repository. Set environment variable ZKEY_REPOSITORY to point to a different location to use a different secure key repository location. Keys stored in a secure key repository inherit the permissions from the repository directory (except write access for other users, which is always denied). The default repository location /etc/zkey/repository is created with group zkeyadm as owner and mode 770. Thus all secure keys created in that repository are owned by group zkeyadm. Anyone who is supposed to access secure keys in the secure key repository must be part of group zkeyadm.

When storing the secure key in a key repository, additional information, such as a textual description of the key, can be associated with a secure key. You can associate a secure key with one or multiple cryptographic adapters (APQNs) that are set up with the same CCA or EP11 master key. You can also associate a secure key with one or multiple volumes (block devices), which are encrypted using dm-crypt with the secure key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. A specific volume can only be associated with one secure key.

The generated secure key is saved in a file, and contains an AES secure key with a length of 128, 192, or 256 bits, or two concatenated AES secure keys with a length of 128, or 256 bits each, for keys that are used for the XTS cipher mode. Note that the file size is not related to the key bit size, but is specific for the secure key type. The key is enciphered with the master key of the CCA or EP11 cryptographic adapter.

Secure keys in a key repository can either be generated locally, or by a key management system (KMS). A key repository can be bound to a key management system (KMS) via a key management system plugin (KMS plugin), which builds the interface to the key management system. This allows one to integrate a zkey key repository into an enterprise key management system, that manages the keys in a larger environment. When a key repository is bound to a key management system, then all keys are generated by the key management system per default, and are thus also bound to the key management system. Any additional information associated with the keys in the repository is also stored in the key management system.

COMMANDS

The zkey tool can operate in two modes. When argument secure-key-file is specified then it operates on the secure key contained in the specified file. This applies to commands generate, validate, reencipher, and convert. When the --name option is specified then it operates on a secure key contained in the secure key repository.

Generating secure AES keys

zkey generate|gen secure-key-file [--keybits|-k size] [--xts|-x] [--clearkey|-c clear-key-file] [--key-type|-K type] [--exportable] [--wrap-with-trusted] [--verbose|-V]

zkey generate|gen --name | -N key-name [--description|-d description] [--volumes|-l volume1:dmname1[,volume2:dmname2[,...]]] [--apqns|-a card1.domain1[,card2.domain2[,...]]] [--no-apqn-check] [--sector-size|-S bytes] [--volume-type|-t type] [--keybits|-k size] [--xts|-x] [--clearkey|-c clear-key-file] [--key-type|-K type] [--local|-L] [--gen-dummy-passphrase] [--set-dummy-passphrase passphrase-file] [--exportable] [--wrap-with-trusted] [KMS-plugin specific options] [--verbose|-V]

Use the generate command to generate a new secure AES key either randomly within the CCA or EP11 cryptographic adapter, from a clear AES key specified as input, or using a key management system plugin (KMS plugin). When specifying a clear key as input, the clear key should be kept in a secure place, or be securely erased after creation of the secure key. The secure key itself does not need to be kept secure, because it can only be used together with a CCA or EP11 cryptographic adapter that contains the master key with which the secure key was generated.

When the secure key repository is bound to a key management system plugin (KMS plugin), then the secure key is generated by using the key management system, except the --local option is specified.

A key management system plugin may offer plugin specific options that can be specified with the generate command. Use generate --help to display the plugin specific options and their meaning.

The generated secure key can either be stored in a file in the file system, or in the secure key repository. To store the generated secure key in a file, specify the file name with option secure-key-file. To store the secure key in the secure key repository, specify the name of the key using the --name option. Secure keys generated using a key management system plugin can only be stored in a secure key repository. When storing the secure key in a key repository, additional information can be associated with a secure key using the --description , --volumes , --apqns , or the --sector-size options. When the secure key repository is bound to a key management system plugin, then you can not associate specific APQNs with such keys, but the keys inherit the APQNs that are associated with the key management system plugin.

You can generate different types of secure keys: CCA-AESDATA keys, CCA-AESCIPHER, and EP11-AES keys. Specify the type of the secure key using the --key-type option. Normally, the default key type is CCA-AESDATA. If the secure key repository is bound to a key management system plugin, and the plugin does not support keys of type CCA-AESDATA, then the default key type is CCA-AESCIPHER, or EP11-AES, whichever the plugin supports.

Note: Secure keys of type CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C. Secure keys of type EP11-AES require an IBM cryptographic adapter in EP11 coprocessor mode of version 7 or later, e.g. a CEX7P.

By default, secure keys of type CCA-AESCIPHER and EP11-AES are export restricted when generated by zkey. Keys of type CCA-AESDATA can not be export restricted. Export restricted means that the secure keys can not be wrapped by a key encrypting key (KEK), and thus can not escape the protection of the IBM cryptographic adapter (HSM). If exportability is required for a secure key of type CCA-AESCIPHER or EP11-AES, specify option --exportable. This makes the generated secure keys exportable. Additionally, for keys of type EP11-AES option --wrap-with-trusted can be specified to allow wrapping only with a trusted KEK. When the secure key repository is bound to a key management system plugin (KMS plugin), options --exportable and --wrap-with-trusted are not allowed, except the --local option is specified.

Note: For keys of type EP11-AES to be exportable, the access control point (ACP) XCP_CPB_ALLOW_COMBINED_EXTRACT must be ON on all APQNs used. This access control point is only supported on newer EP11 firmware levels. If the access control point is OFF or not supported by the EP11 firmware, key generation fails with a generic error (Input/output error). The zkey tool prints an appropriate error message in that case.

Validating secure AES keys

zkey validate|val secure-key-file [--verbose|-V]

zkey validate|val [--name|-N key-name] [--apqns|-a card1.domain1[,card2.domain2[,...]]] [--no-apqn-check] [--verbose|-V]

Use the validate command to validate an existing secure key. It checks if the specified file or repository entry contains a valid secure key. It also displays the attributes of the secure key, such as key sizes, whether it is a secure key that can be used for the XTS cipher mode, the master key register (CURRENT or OLD) with which the secure key is enciphered, and other key attributes. For further information about master key registers, see the reencipher command. Keys of type PVSECRET-AES do not use a cryptographic adapter, thus no master key information is displayed for such keys.

The secure key can either be contained in a file in the file system, or in a secure key repository. To validate a secure key contained in a file, specify the file name with option secure-key-file. To validate secure keys contained in the secure key repository, specify the name of the key or a pattern containing wildcards using the --name option. When wildcards are used you must quote the value. You can also specify the --apqns option to validate those secure keys which are associated with the specified cryptographic adapters (APQNs). You can use wildcards for the APQN specification. When wildcards are used you must quote the value. If both option --name and option --apqns are specified then all secure keys contained in the key repository that match both patterns are validated. If neither option secure-key-file nor options --name or --apqns are specified, then all secure keys contained in the key repository are validated.

Re-encipher existing AES secure keys

zkey reencipher|re secure-key-file [--to-new|-n] [--from-old|-o] [--output|-f output-file] [--verbose|-V]

zkey reencipher|re [--name|-N key-name] [--apqns|-a card1.domain1[,card2.domain2[,...]]] [--to-new|-n] [--from-old|-o] [--in-place|-i] [--staged|-s] [--complete|-c] [--verbose|-V]

Use the reencipher command to re-encipher an existing secure key with a new master key. A secure key must be re-enciphered when the master key of the CCA or EP11 cryptographic adapter changes.

Keys of type PVSECRET-AES can not be re-enciphered. These keys do not use a cryptographic adapter, thus they do not need to be re-enciphered when the master of a cryptographic adapter changes.

The CCA cryptographic adapter has three different registers to store master keys:

  • The CURRENT register contains the current master key.
  • The OLD register contains the previously used master key. Secure keys enciphered with the master key contained in the OLD register can still be used until the master key is changed again.
  • The NEW register contains the new master key to be set. The master key in the NEW register cannot be used until it is made the current master key. You can pro-actively re-encipher a secure key with the NEW master key before this key is made the CURRENT key. Use the --to-new option to do this.

Note: An EP11 cryptographic adapter has only two registers to store master keys, CURRENT and NEW.

Use the --from-old option to re-encipher a secure key that is currently enciphered with the master key in the OLD register with the master key in the CURRENT register. This option is only available for secure keys of type CCA-AESDATA or CCA-AESCIPHER.

If both the --from-old and --to-new options are specified, a secure key that is currently enciphered with the master key in the OLD register is re-enciphered with the master key in the NEW register.

If both options are omitted, zkey automatically detects whether the secure key is currently enciphered with the master key in the OLD register or with the master key in the CURRENT register. If currently enciphered with the master key in the OLD register, it is re-enciphered with the master key in the CURRENT register. If it is currently enciphered with the master key in the CURRENT register, it is re-enciphered with the master key in the NEW register. If for this case the NEW register does not contain a valid master key, then the re-encipher operation fails.

The secure key can either be contained in a file in the file system, or in a secure key repository. To re-encipher a secure key contained in a file, specify the file name with option secure-key-file. To re-encipher secure keys contained in the secure key repository, specify the name of the key or a pattern containing wildcards using the --name option. When wildcards are used you must quote the value. You can also specify the --apqns option to re-encipher those secure keys which are associated with the specified cryptographic adapters (APQNs). You can use wildcards for the APQN specification. When wildcards are used you must quote the value. If both option --name and option --apqns are specified then all secure keys contained in the key repository that match both patterns are re-enciphered. If both options are omitted, then all secure keys contained in the key repository are re-enciphered.

Re-enciphering a secure key contained in the secure key repository can be performed in-place, or in staged mode.

"In-place" immediately replaces the secure key in the repository with the re-enciphered secure key. Re-enciphering from OLD to CURRENT is performed in-place per default. You can use option --in-place to force an in-place re-enciphering for the CURRENT to NEW case. Be aware that a secure key that was re-enciphered in-place from CURRENT to NEW is no longer valid, until the new CCA or EP11 master key has been made the current one.

Staged mode means that the re-enciphered secure key is stored in a separate file in the secure key repository. Thus the current secure key is still valid at this point. Once the new CCA or EP11 master key has been set (made active), you must rerun the reencipher command with option --complete to complete the staged re-enciphering. Re-enciphering from CURRENT to NEW is performed in staged mode per default. You can use option --staged to force a staged re-enciphering for the OLD to CURRENT case.

Note: The reencipher command requires the CCA host library (libcsulcca.so, for) for secure keys of type CCA-AESDATA or CCA-AESCIPHER, or the IBM Z Enterprise PKCS #11 (EP11) Support Program (EP11 host library) for secure keys of type EP11-AES to be installed. For the supported environments and downloads, see: http://www.ibm.com/security/cryptocards

Import existing AES secure keys into the secure key repository

zkey import|im secure-key-file --name | -N key-name [--description|-d description] [--volumes|-l volume1:dmname1[,volume2:dmname2[,...]]] [--apqns|-a card1.domain1[,card2.domain2[,...]]] [--no-apqn-check] [--sector-size|-S bytes] [--volume-type|-t type] [--gen-dummy-passphrase] [--set-dummy-passphrase passphrase-file] [--exportable] [--verbose|-V]

Use the import command to import an existing secure key contained in a file into the the secure key repository. When importing a secure key in a key repository, additional information can be associated with a secure key using the --description , --volumes , --apqns , or the --sector-size options.

Keys of type PVSECRET-AES do not use a cryptographic adapter, thus APQNs can not be associated with them.

Note: The import command requires the CCA host library (libcsulcca.so) to be installed when secure keys of type CCA-AESCIPHER are imported. For the supported environments and downloads, see: http://www.ibm.com/security/cryptocards

By default, secure keys of type CCA-AESCIPHER are changed to be export restricted during the import operation. Export restricted means that the secure keys can not be wrapped by a key encrypting key (KEK), and thus can not escape the protection of the IBM cryptographic adapter (HSM). If exportability of an imported key is required, specify option --exportable. The import operation will then not change the exportability of the secure key.

Export AES secure keys from the secure key repository

zkey export|ex secure-key-file --name | -N key-name [--verbose|-V]

Use the export command to export an existing secure key contained in the secure key repository to a file in the file system. Specify the name of the key that is to be exported using the --name option. You cannot use wildcards. The exported secure key also remains in the secure key repository.

List AES secure keys contained in the secure key repository

zkey list|li [--name|-N key-name] [--volumes|-l volume1[:dmname1][,volume2[:dmname2][,...]]] [--apqns|-a card1.domain1[,card2.domain2[,...]]] [--volume-type|-t type] [--key-type|-K type] [--local|-L] [--kms-bound|-M] [--verbose|-V]

Use the list command to display a list of secure keys contained in the secure key repository. You can filter the displayed list by key name, associated volumes, associated cryptographic adapters (APQNs), volume type, and whether the keys are local or bound to a key management system (MKS). You can use wildcards for the key name, associated APQNs, and associated volumes. The device-mapper name of an associated volume can be omitted; if it is specified then only those keys are listed that are associated with the specified volume and device-mapper name.

The list command displays the attributes of the secure keys, such as key sizes, key type, whether it is a secure key that can be used for the XTS cipher mode, the textual description, associated cryptographic adapters (APQNs) and volumes, the sector size, the key verification pattern, timestamps for key creation, last modification and last re-encipherment, and whether the key is local or bound to a key management system (KMS).

Remove existing AES secure keys from the secure key repository

zkey remove|rem --name | -N key-name [--force|-F] [KMS-plugin specific options] [--verbose|-V]

Use the remove command to remove an existing secure key from the secure key repository. Specify the name of the key that is to be removed using the --name option. You cannot use wildcards. The remove command prompts for a confirmation, unless you specify the --force option.

When the secure key that is to be removed is bound to a key management system, then the key management system plugin might also take an action in the key management system. It may for example change the state of the key in the key management system, instead of removing the key. Nevertheless, the secure key is removed from the local repository.

A key management system plugin may offer plugin specific options that can be specified with the remove command. Use remove --help to display the plugin specific options and their meaning.

Note: When removing a secure key that is associated with one or multiple volumes, and the key's volume type is plain, a message informs you about the associated volumes. When the secure key is removed, these volumes can no longer be used, unless you have a backup of the secure key. For keys with volume type luks2 no such message is issued, because the secure key is contained in the LUKS2 header.

Change existing AES secure keys contained the secure key repository

zkey change|ch --name | -N key-name [--description|-d description] [--volumes|-l [+|-]volume1:dmname1[,volume2:dmname2[,...]]] [--apqns|-a [+|-]card1.domain1[,card2.domain2[,...]]] [--no-apqn-check] [--sector-size|-S bytes] [--volume-type|-t type] [--gen-dummy-passphrase] [--set-dummy-passphrase passphrase-file] [--remove-dummy-passphrase] [--force|-F] [--verbose|-V]

Use the change command to change the description, the associated volumes, the associated cryptographic adapters (APQNs), the sector size, and the volume type of a secure key contained in the secure key repository. Specify the name of the key that is to be changed using the --name option. You cannot use wildcards.

You can set (replace), add, or remove volume and cryptographic adapters (APQN) associations. To set (replace) an association, specify the association with the --volumes or the --apqns options. To add an association, specify the new association prefixed with a + with the --volumes or the --apqns options. To remove an association, specify the association to remove prefixed with a - with the --volumes or the --apqns options. You cannot mix + and - in one specification. You can either add or remove (or set) the associations with one command.

For secure AES keys that are bound to a key management system (KMS) you can not change the APQN association. KMS-bound secure AES keys are always bound to the APQNs that are associated with the key management system plugin. Other associated information is also changed in the key management system when changed using the change command.

For keys of type PVSECRET-AES you can not change or set the APQN association. These keys do not use a cryptographic adapter, thus APQNs can not be associated with them.

Note: The secure key itself cannot be changed, only information about the secure key is changed. To rename a secure key, use the rename command. To re-encipher a secure key with a new CCA or EP11 master key, use the reencipher command.

Rename existing AES secure keys in the secure key repository

zkey rename|ren --name | -N key-name --new-name | -w new-key-name [--verbose|-V]

Use the rename command to rename an existing secure key in the secure key repository. Specify the name of the key that is to be renamed using the --name option and the new name using the --new-name option. You cannot use wildcards. Note: When renaming a secure key that is associated with one or multiple volumes and the key's volume type is plain, a message informs you about the associated volumes. When the secure key is renamed, these volumes can no longer be used, unless you change the name of the secure key in the 'cryptsetup plainOpen' commands and in the '/etc/crypttab' entries. For keys with volume type luks2 no such message is issued, because the secure key is contained in the LUKS2 header.

Copy (duplicate) existing AES secure keys in the secure key repository

zkey copy | co --name|-N key-name --new-name | -w new-key-name [--volumes|-l volume1:dmname1[,volume2:dmname2[,...]]] [--local|-L] [--verbose|-V]

Use the copy command to copy (duplicate) an existing secure key in the secure key repository. Specify the name of the key that is to be copied using the --name option and the name of the copied key using the --new-name option. You cannot use wildcards.

Note: When copying a secure key, the volume associations are not copied, because a specific volume can only be associated with a single secure key. Specify the --volumes option to associate different volumes with the copied secure key, or use the change command to associate volumes afterwards.

You can not copy secure keys that are bound to a key management system (KMS), except when the --local option is specified. The copied secure key is then created as a local key.

Generate crypttab entries for volumes associated with secure AES keys

zkey crypttab|cryptt [--volumes|-l volume1[:dmname1][,volume2[:dmname2][,...]]] [--volume-type|-t type] [--key-file file-name] [--keyfile-offset bytes] [--keyfile-size bytes] [--tries number] [--verbose|-V]

Use the crypttab command to generate crypttab entries using the plain or LUKS2 dm-crypt mode for volumes that are associated with secure keys contained in the secure key repository. Specify the --volumes option to limit the list of volumes where crypttab entries are generated for. You can use wildcards. When wildcards are used you must quote the value. The device-mapper name of an associated volume can be omitted; if it is specified then only those volumes with the specified volume and device-mapper name are selected. Specify the --volume-type option to generate crypttab entries for the specified volume type only.

For LUKS2 volumes, a passphrase is required. You are prompted for the passphrase during system startup when crypttab is evaluated, unless option --key-file is specified, or a dummy passphrase is associated with the secure key. Option --tries specifies how often a passphrase can be re-entered. When option --key-file is specified, the passphrase is read from the specified file. You can specify options --keyfile-offset and --keyfile-size to control which part of the key file is used as passphrase. These options are passed to the generated crypttab entries and are only available if zkey has been compiled with LUKS2 support enabled.

Generate cryptsetup commands for volumes associated with secure AES keys

zkey cryptsetup|crypts [--volumes|-l volume1[:dmname1][,volume2[:dmname2][,...]]] [--volume-type|-t type] [--run|-r] [--open] [--format] [--key-file file-name] [--keyfile-offset bytes] [--keyfile-size bytes] [--tries number] [--batch-mode|-q] [--verbose|-V]

Use the cryptsetup command to generate cryptsetup plainOpen, cryptsetup luksOpen, or cryptsetup luksFormat commands for volumes that are associated with secure keys contained in the secure key repository. Specify the --volumes option to limit the list of volumes where cryptsetup commands are generated for. You can use wildcards. When wildcards are used you must quote the value. The device-mapper name of an associated volume can be omitted; if it is specified then only those volumes with the specified volume and device-mapper name are selected. Specify the --volume-type option to generate cryptsetup commands for the specified volume type only. Specify the --run option to run the generated cryptsetup commands. Specify the --open to generate cryptsetup plainOpen or cryptsetup luksOpen commands. For the plain volume type, this is the default. Specify the --format option to generate cryptsetup luksFormat commands. For the LUKS2 volume type, this is the default. If specified for the plain volume type, then no command is generated.

For LUKS2 volumes, the generated cryptsetup luksFormat contains options --pbkdf argon2i --pbkdf-memory 32 --pbkdf-force-iterations 4 for low memory and time requirements. Using the default Argon2i options might cause out-of-memory errors when multiple encrypted volumes are unlocked automatically at boot through /etc/crypttab. In case the system runs in FIPS mode, --pbkdf pbkdf2 is used instead, because Argon2i might be disabled by a policy when FIPS mode is active. Because PAES uses secure AES keys as volume keys, the security of the key derivation function used to encrypt the volume key in the LUKS key slots is of less relevance.

For LUKS2 volumes, a passphrase is required. You are prompted for the passphrase when running the generated commands, unless option --key-file is specified, or a dummy passphrase is associated with the secure key. Option --tries specifies how often a passphrase can be re-entered. When option --key-file is specified, the passphrase is read from the specified file. You can specify options --keyfile-offset and --keyfile-size to control which part of the key file is used as passphrase. These options are only available if zkey has been compiled with LUKS2 support enabled. To avoid cryptsetup confirmation questions, you can specify the --batch-mode option. These options are passed to the generated command(s) and behave in the same way as with cryptsetup.

Convert existing AES secure keys from one key type to another type

zkey convert|con secure-key-file --key-type|-K type [--no-apqn-check] [--force|-F] [--verbose|-V]

zkey convert|con --name | -N key-name --key-type|-K type [--no-apqn-check] [--force|-F] [--exportable] [--verbose|-V]

Use the convert command to convert an existing secure key from one key type to another type. You can convert secure keys of type CCA-AESDATA to type CCA-AESCIPHER only. You can not convert keys that are bound to a key management system (KMS).

Note: Secure keys converted to type CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C.

The secure key can either be contained in a file in the file system, or in a secure key repository. To convert a secure key contained in a file, specify the file name with option secure-key-file. To convert a secure key contained in the secure key repository, specify the name of the key that is to be converted using the --name option. You cannot use wildcards. The convert command prompts for a confirmation, unless you specify the --force option.

Note: Converting a secure key is irreversible! When converting a secure key that is associated with one or multiple volumes, a message informs you about the associated volumes. When the secure key is converted, this might have an effect on these volumes.

For volumes with volume type plain, you must adapt the crypttab entries and change the key size parameter to size=<new-key-size-in-bits> or run command zkey crypttab --volumes <device> for each associated volume to re-generate the crypttab entries.

Associated volumes of type LUKS2 still contain the secure AES volume key of the original type. To change the secure AES volume key in the LUKS2 header, run command zkey-cryptsetup setkey <device> --master-key-file <converted-key> for each associated volume.

Note: The convert command requires the CCA host library (libcsulcca.so) to be installed. The required CCA IBM cryptographic adapter firmware version is 6.3.27 or later. For the supported environments and downloads, see: http://www.ibm.com/security/cryptocards

By default, secure keys are changed to be export restricted during the convert operation. Export restricted means that the secure keys can not be wrapped by a key encrypting key (KEK), and thus can not escape the protection of the IBM cryptographic adapter (HSM). If exportability of a converted key is required, specify option --exportable. The convert operation will then not change the exportability of the secure key.

COMMANDS FOR KEY MANAGEMENT SYSTEM INTEGRATION

Use the kms command to control the integration into key management systems. The kms command offers several subcommands for key management specific operations. Use zkey kms --help to show the available subcommands.

List key management system plugins

zkey kms plugins|pl [--verbose|-V]

Use the kms plugins command to display a list of configured key management system plugins (KMS plugins). It displays the key management system plugin name, and the shared library that implements the plugin.

Key management system plugins are configured in configuration file /etc/zkey/kms-plugins.conf. This file contains the KMS plugin name and its shared library. Set environment variable ZKEY_KMS_PLUGINS to point to a different file to use a different KMS plugin configuration file.

Bind the repository to a key management system

zkey kms bind|bi KMS-plugin-name [--verbose|-V]

Use the kms bind command to bind the repository to a key management system (KMS). The kms plugins command displays a list of configured key management system plugins that can be used.

After binding a repository to a key management system, the KMS plugin must first be configured. Use the kms configure command to configure the plugin. As a minimum, you must associate APQNs with the key management system plugin. The plugin may require additional configuration before it is fully functioning. Use the kms info command to display information about the key management system plugin and its configuration.

When a key repository is bound to a key management system, then all keys are generated by this key management system per default, and are thus also bound to the key management system. Any additional information associated with the keys in the repository is also stored in the key management system.

Unbind the repository from a key management system

zkey kms unbind|unb [--verbose|-V]

Use the kms unbind command to unbind the repository from a key management system (KMS). All keys that are currently bound to the key management system, are unbound and become local keys. You are prompted to confirm the unbinding.

Display information about a key management system plugin

zkey kms info|in [--verbose|-V]

Use the kms info command to display information about the currently bound key management system plugin (KMS plugin) and its configuration.

Configure or re-configure a key management system plugin

zkey kms configure|con [--apqns|-a [+|-]card1.domain1[,card2.domain2[,...]]] [KMS-plugin specific options] [--verbose|-V]

Use the kms configure command to configure or re-configure the currently bound key management system plugin (KMS plugin). As a minimum, you must associate APQNs with the key management system plugin. The plugin may require an initial configuration before it is fully functioning. Once configured, a plugin may allow you to change some configuration settings.

A key management system plugin may offer plugin specific options that can be specified with the kms configure command. Use kms configure --help to display the plugin specific options and their meaning.

Configuring a key management system plugin may be a multi-step task. You can supply all configuration options at once or use the kms configure command several times supplying only one or a few configuration options each time, dependent on what the plugin supports. A plugin may also require to perform additional intermediate steps between two configuration attempts, e.g. perform tasks in the key management system user interface, or elsewhere.

Use the kms info command to display information about the key management system plugin and its current configuration.

Re-encipher secure keys used by a key management system plugin

zkey kms reencipher|re [--to-new|-n] [--from-old|-o] [--in-place|-i] [--staged|-s] [--complete|-c] [KMS-plugin specific options] [--verbose|-V]

Use the kms reencipher command to re-encipher secure keys internally used by the currently bound key management system plugin (KMS plugin) with a new master key. This command must be run when the master keys of the CCA or EP11 cryptographic adapter, that are associated with the plugin have been changed. Dependent on what key types the key management system plugin supports, it may internally use secure keys with CCA or EP11 cryptographic adapters, or both.

A key management system plugin may offer plugin specific options that can be specified with the kms reencipher command. Use kms reencipher --help to display the plugin specific options and their meaning.

Note: The kms reencipher command does not re-encipher secure keys that have been generated by or have been imported from the key management system plugin and are stored in the repository. Use the regular reencipher command to re-encipher those secure keys.

The CCA cryptographic adapter has three different registers to store master keys:

  • The CURRENT register contains the current master key.
  • The OLD register contains the previously used master key. Secure keys enciphered with the master key contained in the OLD register can still be used until the master key is changed again.
  • The NEW register contains the new master key to be set. The master key in the NEW register cannot be used until it is made the current master key. You can pro-actively re-encipher a secure key with the NEW master key before this key is made the CURRENT key. Use the --to-new option to do this.

Note: An EP11 cryptographic adapter has only two registers to store master keys, CURRENT and NEW.

Use the --from-old option to re-encipher a secure key that is currently enciphered with the master key in the OLD register with the master key in the CURRENT register. This option is only available for CCA-type secure keys.

If both the --from-old and --to-new options are specified, a secure key that is currently enciphered with the master key in the OLD register is re-enciphered with the master key in the NEW register.

If both options are omitted, the key management system plugin may automatically detect whether the secure key is currently enciphered with the master key in the OLD register or with the master key in the CURRENT register. If currently enciphered with the master key in the OLD register, it is re-enciphered with the master key in the CURRENT register. If currently enciphered with the master key in the CURRENT register, it is re-enciphered with the master key in the NEW register. If for this case the NEW register does not contain a valid master key, then the re-encipher operation fails.

Re-enciphering a secure key used by a key management system plugin can be performed in-place, or in staged mode.

"In-place" immediately replaces the secure key with the re-enciphered secure key. Re-enciphering from OLD to CURRENT is performed in-place per default. You can use option --in-place to force an in-place re-enciphering for the CURRENT to NEW case. A secure key that was re-enciphered in-place from CURRENT to NEW is no longer valid, until the new CCA or EP11 master key has been made the current one.

Staged mode means that the re-enciphered secure key is stored separately. Thus the current secure key is still valid at this point. Once the new CCA or EP11 master key has been set (made active), you must rerun the kms reencipher command with option --complete to complete the staged re-enciphering. Re-enciphering from CURRENT to NEW is performed in staged mode per default. You can use option --staged to force a staged re-enciphering for the OLD to CURRENT case.

List secure keys managed by a key management system

zkey kms list|li [--label|-B key-label] [--name|-N key-name] [--volumes|-l volume1[:dmname1][,volume2[:dmname2][,...]]] [--volume-type|-t type] [KMS-plugin specific options] [--verbose|-V]

Use the kms list command to display secure keys managed by a key management system (KMS). You can filter the displayed list by key label, key name, associated volumes, and volume type. You can use wildcards for the key label, key name, and associated volumes. The device-mapper name of an associated volume can be omitted. If specified, then only those keys are listed that are associated with the specified volume and device-mapper name.

A key management system plugin may offer plugin specific options that can be specified with the kms list command. Use kms list --help to display the plugin specific options and their meaning.

The kms list command displays the attributes of the secure keys, such as key label, key name, whether it is a secure key that can be used for the XTS cipher mode, the textual description, associated volumes, the volume type, and sector size.

Import secure keys managed by a key management system into the repository

zkey kms import|im [--label|-B key-label] [--name|-N key-name] [--volumes|-l volume1[:dmname1][,volume2[:dmname2][,...]]] [--volume-type|-t type] [--batch-mode|-q] [--no-volume-check] [KMS-plugin specific options] [--verbose|-V]

Use the kms import command to import secure keys managed by a key management system (KMS) 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. You can use wildcards for the key label, key name, and associated volumes. The device-mapper name of an associated volume can be omitted. If it is specified, then only those keys are listed that are associated with the specified volume and device-mapper name.

A key management system plugin may offer plugin specific options that can be specified with the kms import command. Use kms import --help to display the plugin specific options and their meaning.

If a secure key with the same name as a key to be imported already exists in the repository, then you are prompted to enter an alternate name. You can skip the import of that key, or enter an alternate name. If option --batch-mode is specified, then already existing keys are skipped.

If a key to be imported is associated with one or multiple volumes, it is verified that the volumes are available, and are not already associated with another secure key in the repository. If one of the volumes or all of them are not available, or are already associated with another secure key, the import fails. Use option --no-volume-check to omit the volume check, and import the keys even if the associated volume(s) do not exist.

Refresh secure keys that are bound to a key management system

zkey kms refresh|ref [--name|-N key-name] [--volumes|-l volume1[:dmname1][,volume2[:dmname2][,...]]] [--volume-type|-t type] [--key-type|-K type] [--refresh-properties|-P] [--no-volume-check] [--verbose|-V]

Use the kms refresh command to refresh secure keys that are bound to a key management system (KMS). Refreshing a key updates the secure key by re-importing it from the key management system. 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 in the key management system.

You can filter the list of keys to be refreshed by key name, associated volumes, volume type, and key type. You can use wildcards for the key name, and associated volumes. The device-mapper name of an associated volume can be omitted; if it is specified then only those keys are listed that are associated with the specified volume and device-mapper name.

If a refreshed key is associated with one or multiple volumes, it is verified that the volumes are available, and are not already associated with another secure key in the repository. If one of the volumes or all of them are not available, or are already associated with another secure key, the refresh fails. Use option --no-volume-check to omit the volume check, and refresh the keys even if the associated volume(s) do not exist.

COMMANDS FOR PROTECTED VIRTUALIZATION

Use the pvsecrets command to work with protected virtualization (PV) secrets. Protected virtualization secrets can be made available to a secure execution guest and can be used only within that guest. The pvsecrets command provides subcommands for protected virtualization specific operations. Use zkey pvsecrets --help to show the available subcommands. These subcommands only work when running in a secure execution guest. Only the root user is allowed to perform these subcommands.

List available protected virtualization secrets

zkey pvsecrets list|li [--all|-A] [--hex|-H] [--pvsecret-type|-T pvsecret-type] [--pvsecret-id|-I pvsecret-id] [--pvsecret-name|-e pvsecret-name] [--verbose|-V]

Use the pvsecrets list command to display a list of protected virtualization (PV) secrets. It displays the pvsecret ID as hex string of 32 bytes or as printable name enclosed in single quotes ('), if the pvsecret ID consists of only printable characters. Specify the --hex option to list all pvsecret IDs as hex string. The pvsecrets list command also shows the pvsecret type of each secret.

You can filter the list of pvsecrets by pvsecret ID, pvsecret name and pvsecret type. Either the --pvsecret-id option or the --pvsecret-name option can be specified. By default the pvsecrets list command displays only those pvsecrets with types that are supported by the zkey tool. To list all pvsecret types, specify the --all option.

This command is only available when running in a secure execution guest. Only the root user is allowed to perform this command.

Import protected virtualization secrets into the repository

zkey pvsecrets import|im [--pvsecret-id|-I pvsecret-id] [--pvsecret-name|-e pvsecret-name] --name | -N key-name [--description|-d description] [--volumes|-l volume1:dmname1[,volume2:dmname2[,...]]] [--sector-size|-S bytes] [--volume-type|-t type] [--gen-dummy-passphrase] [--set-dummy-passphrase passphrase-file] [--verbose|-V]

Use the pvsecrets import command to import a protected virtualization (PV) secret into the repository. Either the --pvsecret-id option or the --pvsecret-name option can be specified. If the pvsecret name is specified, then the --name option can be omitted. The name of the protected virtualization secret key object in the repository will then be the same as the pvsecret name.

You can use the YAML file that was created when using the pvsecret create command for adding the protected virtualization secret: --pvsecret-id "$(yq .id YAML-FILE)" or --pvsecret-name "$(yq .name YAML-FILE)". You might have to install the yq package first.

A protected virtualization secret key object does not contain the key material, but only a reference (i.e. the secret ID) to the key in the ultravisor. When such a protected virtualization secret key object is used with dm-crypt and the PAES kernel cipher, the key material (i.e. a protected key) is retrieved from the ultravisor and the crypto operation is performed with it.

When importing a protected virtualization secret in a key repository, additional information can be associated with it using the --description , --volumes , or the --sector-size options. APQNs can not be associated, because protected virtualization secrets do not require a crypto card.

This command is only available when running in a secure execution guest. Only the root user is allowed to perform this command.

OPTIONS

Options for the generate command

Specifies the size of the AES key to be generated in bits. Valid values are 128, 192, and 256. Secure keys for use with the XTS cipher mode can only use keys of 128 or 256 bits. The default is 256 bits.
Generates a secure AES key for the XTS cipher mode that consist of two concatenated secure keys.
Specifies a file path that contains the clear AES key in binary form. If option --keybits is omitted, the size of the specified file determines the size of the AES key. If option --keybits is specified, the size of the specified file must match the specified key size. Valid file sizes are of 16, 24, or 32 bytes, and of 32 or 64 bytes for keys to be used with the XTS cipher mode. When the secure key is generated using a key management system, then this option can not be specified.
Specifies the name of the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository.
Specifies a textual description for the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of volumes (block devices) that are associated with the secure AES key in the repository. These volumes are to be encrypted using dm-crypt with the secure AES key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. A specific volume can only be associated with a single secure key. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) which are associated with the secure AES key in the repository. Each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it). When at least one APQN is specified, then the first online APQN is used to generate the key. If no APQNs are specified, then an APQN is selected automatically. All specified APQNs must be online, unless the --no-apqn-check option is specified. This option is only used for secure keys contained in the secure key repository. When the secure key is generated using a key management system, then this option can not be specified.
Do not check if the specified APQNs are available. Use this option to associate APQNs with a secure AES key that are currently not available. This option is only used for secure keys contained in the secure key repository.
Specifies the sector size in bytes used with dm-crypt. It must be a power of two and in the range of 512 to 4096 bytes. If omitted, the system default sector size is used. This option is only used for secure keys contained in the secure key repository.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. If omitted, luks2 is used. This option is only available if zkey has been compiled with LUKS2 support enabled. If LUKS2 support is not enabled, the default volume type is plain. This option is only used for secure keys contained in the secure key repository.
Specifies the key type of the secure key. Possible values are CCA-AESDATA, CCA-AESCIPHER, and EP11-AES. If this option is omitted, then a secure key of type CCA-AESDATA is generated. Secure keys of type CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C. Secure keys of type EP11-AES require an IBM cryptographic adapter in EP11 coprocessor mode of version 7 or later, e.g. a CEX7P.
Generate the secure AES key locally. This is the default when no key management system plugin (KMS plugin) is bound to the secure key repository. If the repository is bound to a key management system plugin, then keys are generated using the key management system by default.
Generate a dummy passphrase randomly and associate it with the secure AES key used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance for the security of the volume(s), when an secure AES key is used to encrypt the volume(s), and can therefore be stored insecurely inside the secure key repository. If for a certain usage the passphrase is of relevance for security, then do not use this option. This option can only be specified for keys with a volume type of luks2. This option is only used for secure keys contained in the secure key repository.
Set a dummy passphrase that is read from the specified file and associate it with the secure AES key used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance for the security of the volume(s), when an secure AES key is used to encrypt the volume(s), and can therefore be stored insecurely inside the secure key repository. If for a certain usage the passphrase is of relevance for security, then do not use this option. This option can only be specified for keys with a volume type of luks2. This option is only used for secure keys contained in the secure key repository.
A key management system plugin may offer and even require plugin specific options that can be specified with the generate command when the secure key repository is bound to a key management system plugin. Use generate --help to display the plugin specific options and their meaning.

Options for the validate command

Specifies the name of the secure key in the secure key repository. You can use wildcards to select multiple secure keys in the secure key repository. When wildcards are used you must quote the value. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQNs). You can use wildcards in the APQN specification. All secure keys contained in the secure key repository which are associated with the specified APQNs are validated. Each APQN specifies a card and domain number separated by a period (like lszcrypt displays it). This option is only used for secure keys contained in the secure key repository.
Do not check if the associated APQNs are available. This option is only used for secure keys contained in the secure key repository.

Options for the reencipher command

Re-enciphers a secure AES key that is currently enciphered with the master key in the CURRENT register with the master key in the NEW register.
Re-enciphers a secure AES key that is currently enciphered with the master key in the OLD register with the master key in the CURRENT register. This option is only available for secure keys of type CCA-AESDATA and CCA-AESCIPHER.
Specifies the name of the output file to which the re-enciphered secure key is written. If this option is omitted, the re-enciphered secure key is replaced in the file that currently contains the secure key. This option is only used for secure keys stored in a file in the file system. It is not valid for keys contained in the secure key repository.
Specifies the name of the secure key in the secure key repository. You can use wildcards to select multiple secure keys in the secure key repository. When wildcards are used you must quote the value. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQNs). You can use wildcards in the APQN specification. All secure keys contained in the secure key repository which are associated with the specified APQNs are re-enciphered. Each APQN specifies a card and domain number separated by a period (like lszcrypt displays it). This option is only used for secure keys contained in the secure key repository.
Forces an in-place re-enciphering of a secure AES key contained in the secure key repository. "In-place" immediately replaces the secure key in the repository with the re-enciphered secure key. Re-enciphering from OLD to CURRENT is performed in-place per default. This option is only used for secure keys contained in the secure key repository.
Forces that the re-enciphering of a secure AES key contained in the secure key repository is performed in staged mode. Staged mode means that the re-enciphered secure key is stored in a separate file in the secure key repository. Thus the current secure key is still valid at this point. Once the new CCA or EP11 master key has been set (made active), you must rerun the reencipher command with option --complete to complete the staged re-enciphering. Re-enciphering from CURRENT to NEW is performed in staged mode per default. This option is only used for secure keys contained in the secure key repository.
Completes a staged re-enciphering. Use this option after the new CCA or EP11 master key has been set (made active). This option replaces the secure key by its re-enciphered version in the secure key repository. This option is only used for secure keys contained in the secure key repository.

Options for the import command

Specifies the name of the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository.
Specifies a textual description for the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of volumes (block devices) which are associated with the secure AES key in the repository. These volumes are to be encrypted using dm-crypt with the secure AES key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. A specific volume can only be associated with a single secure key. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) which are associated with the secure AES key in the repository. Each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it). All specified APQNs must be online, unless option --no-apqn-check is specified. This option is only used for secure keys contained in the secure key repository.
Do not check if the specified APQNs are available. Use this option to associate APQNs with a secure AES key that are currently not available. This option is only used for secure keys contained in the secure key repository.
Specifies the sector size in bytes used with dm-crypt. It must be a power of two and in the range of 512 to 4096 bytes. If omitted, the system default sector size is used. This option is only used for secure keys contained in the secure key repository.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. If omitted, luks2 is used. This option is only available if zkey has been compiled with LUKS2 support enabled. If LUKS2 support is not enabled, the default volume type is plain. This option is only used for secure keys contained in the secure key repository.
Generate a dummy passphrase randomly and associate it with the secure AES key used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance for the security of the volume(s), when an secure AES key is used to encrypt the volume(s), and can therefore be stored insecurely inside the secure key repository. If for a certain usage the passphrase is of relevance for security, then do not use this option. This option can only be specified for keys with a volume type of luks2. This option is only used for secure keys contained in the secure key repository.
Set a dummy passphrase that is read from the specified file and associate it with the secure AES key used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance for the security of the volume(s), when an secure AES key is used to encrypt the volume(s), and can therefore be stored insecurely inside the secure key repository. If for a certain usage the passphrase is of relevance for security, then do not use this option. This option can only be specified for keys with a volume type of luks2. This option is only used for secure keys contained in the secure key repository.

Options for the export command

Specifies the name of the secure key in the secure key repository. You cannot use wildcards. This option is only used for secure keys contained in the secure key repository.

Options for the list command

Specifies the name of the secure key in the secure key repository. You can use wildcards to select multiple secure keys in the secure key repository. When wildcards are used you must quote the value. Only keys with names that match the pattern are listed. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of volumes (block devices) which are associated with the secure AES key in the repository. Only those keys are listed, which are associated with the specified volumes. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. You can omit the device-mapper name; if it is specified then only those keys are listed that are associated with the specified volume and device-mapper name. You can use wildcards to specify the volumes and device-mapper names. When wildcards are used you must quote the value. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) which are associated with the secure AES key in the repository. Only those keys are listed, which are associated with the specified APQNs. Each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it). You can use wildcards in the APQN specification. This option is only used for secure keys contained in the secure key repository.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. Only keys with the specified volume type are listed. This option is only available if zkey has been compiled with LUKS2 support enabled. This option is only used for secure keys contained in the secure key repository.
Specifies the key type of the secure key. Possible values are CCA-AESDATA, CCA-AESCIPHER, EP11-AES, and PVSECRET-AES. Only keys with the specified key type are listed. This option is only used for secure keys contained in the secure key repository.
Lists only local keys. Local keys are not bound to a key management system (KMS). This option is only used for secure keys contained in the secure key repository, and can not be specified together with the --kms-bound option.
Lists only keys that are bound to a key management system (KMS). This option is only used for secure keys contained in the secure key repository, and can not be specified together with the --local option.

Options for the remove command

Specifies the name of the secure key in the secure key repository. You cannot use wildcards. This option is only used for secure keys contained in the secure key repository.
The user is prompted to confirm the removal of a secure key from the secure key repository. Use this option to remove a secure key without prompting for a confirmation. This option is only used for secure keys contained in the secure key repository.
A key management system plugin may offer and even require plugin specific options that can be specified with the remove command when the secure key repository is bound to a key management system plugin. Use remove --help to display the plugin specific options and their meaning.

Options for the change command

Specifies the name of the secure key in the secure key repository. You cannot use wildcards. This option is only used for secure keys contained in the secure key repository.
Specifies a textual description for the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of volumes (block devices) which are associated with the secure AES key in the repository. These volumes are to be encrypted using dm-crypt with the secure AES key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. To add a volume to the associated volumes, prefix the volume with a +. To remove a volume from the associated volumes, prefix the volume with a -. To set (replace) the volume association do not specify a prefix. You cannot mix + and - in one specification. You can either add or remove (or set) the associations with one command. A specific volume can only be associated with a single secure key. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) which are associated with the secure AES key in the repository. Each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it). To add an APQN to the associated APQNs, prefix the APQN with a +. To remove an APQN from the associated APQNs, prefix the APQN with a -. To set (replace) the APQN association do not specify a prefix. You cannot mix + and - in one specification. You can either add or remove (or set) the associations with one command. All APQNs being added or set (replaced) must be online, unless option --no-apqn-check is specified. This option is only used for secure keys contained in the secure key repository.
Do not check if the specified APQNs are available. Use this option to associate APQNs with a secure AES key that are currently not available. This option is only used for secure keys contained in the secure key repository.
Specifies the sector size in bytes used with dm-crypt. It must be a power of two and in the range of 512 to 4096 bytes. Specify 0 to set the sector size to the system default. This option is only used for secure keys contained in the secure key repository.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. This option is only available if zkey has been compiled with LUKS2 support enabled. This option is only used for secure keys contained in the secure key repository.
Generate a dummy passphrase randomly and associate it with the secure AES key used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance for the security of the volume(s), when an secure AES key is used to encrypt the volume(s), and can therefore be stored insecurely inside the secure key repository. If for a certain usage the passphrase is of relevance for security, then do not use this option. This option can only be specified for keys with a volume type of luks2. When there is already a dummy passphrase associated with the key, you must first remove the dummy passphrase with option --remove-dummy-passphrase before you can associate a new dummy passphrase. This option is only used for secure keys contained in the secure key repository.
Set a dummy passphrase that is read from the specified file and associate it with the secure AES key used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance for the security of the volume(s), when an secure AES key is used to encrypt the volume(s), and can therefore be stored insecurely inside the secure key repository. If for a certain usage the passphrase is of relevance for security, then do not use this option. This option can only be specified for keys with a volume type of luks2. When there is already a dummy passphrase associated with the key, you must first remove the dummy passphrase with option --remove-dummy-passphrase before you can associate a new dummy passphrase. This option is only used for secure keys contained in the secure key repository.
Remove the associated dummy passphrase used with LUKS2 volume(s). The user is prompted to confirm the removal of the associated dummy passphrase. Use the --force option to remove the associated dummy passphrase without prompting for a confirmation. This option is only used for secure keys contained in the secure key repository.
The user is prompted to confirm the removal of the associated dummy passphrase. Use this option to remove the associated dummy passphrase without prompting for a confirmation. This option is only used for secure keys contained in the secure key repository, and can only be specified together with option --remove-dummy-passphrase.

Options for the rename command

Specifies the name of the secure key in the secure key repository. You cannot use wildcards. This option is only used for secure keys contained in the secure key repository.
Specifies the new name of the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository.

Options for the copy command

Specifies the name of the secure key to be copied in the secure key repository. You cannot use wildcards. This option is only used for secure keys contained in the secure key repository.
Specifies the new name of the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository.
Volume associations are not copied, because a volume can only be associated with a single secure key. To associate different volumes with the copied secure AES key, specify a comma-separated list of volumes (block devices). These volumes are to be encrypted usingdm-crypt with the secure AES key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. This option is only used for secure keys contained in the secure key repository.
Copy the secure key to a local key. This is the default when no key management system plugin (KMS plugin) is bound to the secure key repository. If the repository is bound to a key management system plugin, then the keys are bound to the KMS per default, and KMS-bound keys can only be copied to local keys.

Options for the crypttab command

Specifies a comma-separated list of volumes (block devices) which are associated with secure AES keys in the repository. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. You can omit the device-mapper name; if it is specified then only those keys are selected that are associated with the specified volume and device-mapper name. You can use wildcards to specify the volumes and device-mapper names. When wildcards are used you must quote the value. This option is only used for secure keys contained in the secure key repository.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. Only keys with the specified volume type are selected to generate crypttab entries for. This option is only available if zkey has been compiled with LUKS2 support enabled. This option is only used for secure keys contained in the secure key repository.
Reads the passphrase from the specified file. If this option is omitted, and no dummy passphrase is associated with the secure key, then you are prompted to enter the passphrase interactively during system startup. This option is passed to the generated crypttab entries for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled.
Specifies the number of bytes to skip before starting to read in the file specified with option --key-file. If omitted, the file is read from the beginning. When option --key-file is not specified, this option is ignored. This option is passed to the generated crypttab entries for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled. Not all distributions support the keyfile-offset option in crypttab entries.
Specifies the number of bytes to be read from the beginning of the file specified with option --key-file. If omitted, the file is read until the end. When --keyfile-offset is also specified, reading starts at the offset. When option --key-file is not specified, this option is ignored. This option is passed to the generated crypttab entries for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled. Not all distributions support the keyfile-size option in crypttab entries.
Specifies how often the interactive input of the passphrase can be re-entered during system startup. The default is 3 times. When option --key-file is specified, this option is ignored, and the passphrase is read only once from the file. This option is passed to the generated crypttab entries for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled.

Options for the cryptsetup command

Specifies a comma-separated list of volumes (block devices) which are associated with secure AES keys in the repository. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. You can omit the device-mapper name; if it is specified then only those keys are selected that are associated with the specified volume and device-mapper name. You can use wildcards to specify the volumes and device-mapper names. When wildcards are used you must quote the value. This option is only used for secure keys contained in the secure key repository.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. Only keys with the specified volume type are selected to generate cryptsetup commands for. This option is only available if zkey has been compiled with LUKS2 support enabled. This option is only used for secure keys contained in the secure key repository.
Runs the generated cryptsetup commands. When one of the cryptsetup commands fail, no further cryptsetup commands are run, and zkey ends with an error. This option is only used for secure keys contained in the secure key repository.
Generates cryptsetup luksOpen or cryptsetup plainOpen commands. For a plain volume type, this is the default. This option can not be specified together with the --format option, and is only available if zkey has been compiled with LUKS2 support enabled.
Generates cryptsetup luksFormat commands. For a LUKS2 volume type, this is the default. If specified for a plain volume type, then no command is generated. This option can not be specified together with the --open option, and is only available if zkey has been compiled with LUKS2 support enabled.
Reads the passphrase from the specified file. If this option is omitted, and no dummy passphrase is associated with the secure key, or if the file-name is - (a dash), then you are prompted to enter the passphrase interactively. This option is passed to the generated command(s) for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled.
Specifies the number of bytes to skip before starting to read in the file specified with option --key-file. If omitted, the file is read from the beginning. When option --key-file is not specified, this option is ignored. This option is passed to the generated command(s) for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled.
Specifies the number of bytes to be read from the beginning of the file specified with option --key-file. If omitted, the file is read until the end. When --keyfile-offset is also specified, reading starts at the offset. When option --key-file is not specified, this option is ignored. This option is passed to the generated command(s) for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled.
Specifies how often the interactive input of the passphrase can be re-entered. The default is 3 times. When option --key-file is specified, this option is ignored, and the passphrase is read only once from the file. This option is passed to the generated command(s) for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled.
Suppress cryptsetup confirmation questions. This option is passed to the generated cryptsetup command(s).

Options for the convert command

Specifies the name of the secure key in the secure key repository. You cannot use wildcards. This option is only used for secure keys contained in the secure key repository.
Specifies the key type to which the secure key shall be converted to. Possible values are CCA-AESCIPHER. Secure keys of type CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C.
Do not check if the associated APQNs are available and capable of converting the secure key to type CCA-AESCIPHER. This option is only used for secure keys contained in the secure key repository.
The user is prompted to confirm the conversion of a secure key. Use this option to convert a secure key without prompting for a confirmation.

Options for the kms configure command

Specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) which are associated with the key management system plugin. Each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it). To add an APQN to the associated APQNs, prefix the APQN with a +. To remove an APQN from the associated APQNs, prefix the APQN with a -. To set (replace) the APQN association do not specify a prefix. You cannot mix + and - in one specification. You can either add or remove (or set) the associations with one command. All APQNs being added or set (replaced) must be online.
A key management system plugin may offer plugin specific options that can be specified with the kms configure command. Use kms configure --help to display the plugin specific options and their meaning.

Options for the kms reencipher command

Re-enciphers key management system plugin internal secure keys that are currently enciphered with the master key in the CURRENT register with the master key in the NEW register.
Re-enciphers key management system plugin internal secure keys that are currently enciphered with the master key in the OLD register with the master key in the CURRENT register. This option is only available for CCA-type secure keys.
Forces an in-place re-enciphering of key management system plugin internal secure keys. "in-place" immediately replaces the secure key with the re-enciphered secure key. Re-enciphering from OLD to CURRENT is performed in-place per default.
Forces that the re-enciphering of key management system plugin internal secure keys is performed in staged mode. Staged mode means that the re-enciphered secure keys are stored separately. Thus the current secure keys are still valid at this point. Once the new CCA or EP11 master keys have been set (made active), you must rerun the kms reencipher command with option --complete to complete the staged re-enciphering. Re-enciphering from CURRENT to NEW is performed in staged mode per default.
Completes a staged re-enciphering. Use this option after the new CCA or EP11 master keys have been set (made active). This option replaces the secure keys by their re-enciphered versions.
A key management system plugin may offer plugin specific options that can be specified with the kms reencipher command. Use kms reencipher --help to display the plugin specific options and their meaning.

Options for the kms list command

Specifies the label of the secure key in the key management system (KMS). You can use wildcards to select multiple secure keys. When wildcards are used you must quote the value. Only keys with labels that match the pattern are listed.
Specifies the name of the secure key in the key management system (KMS). You can use wildcards to select multiple secure keys. When wildcards are used you must quote the value. Only keys with names that match the pattern are listed. This option is only used for secure keys contained in the secure key repository.
Specifies a comma-separated list of volumes (block devices) which are associated with the secure AES key in the key management system (KMS). Only those keys are listed, which are associated with the specified volumes. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. You can omit the device-mapper name; if it is specified then only those keys are listed that are associated with the specified volume and device-mapper name. You can use wildcards to specify the volumes and device-mapper names. When wildcards are used you must quote the value.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. Only keys with the specified volume type are listed. This option is only available if zkey has been compiled with LUKS2 support enabled.

Options for the kms import command

Specifies the label of the secure key in the key management system (KMS). You can use wildcards to select multiple secure keys. When wildcards are used you must quote the value. Only keys with labels that match the pattern are imported.
Specifies the name of the secure key in the key management system (KMS). You can use wildcards to select multiple secure keys. When wildcards are used you must quote the value. Only keys with names that match the pattern are imported.
Specifies a comma-separated list of volumes (block devices) which are associated with the secure AES key in the key management system (KMS). Only those keys are imported, which are associated with the specified volumes. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. You can omit the device-mapper name; if it is specified then only those keys are listed that are associated with the specified volume and device-mapper name. You can use wildcards to specify the volumes and device-mapper names. When wildcards are used you must quote the value.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. Only keys with the specified volume type are imported. This option is only available if zkey has been compiled with LUKS2 support enabled.
Suppress prompts to skip or to enter an alternate name, if a secure key with the same name as the secure key to be imported already exists in the repository. When this option is specified, then keys with an existing name are skipped.
Do not check if the volume(s) associated with the to be imported secure key(s) are available, or are already associated with other secure keys in the repository.

Options for the kms refresh command

Specifies the name of the secure key in the secure key repository. You can use wildcards to select multiple secure keys in the secure key repository. When wildcards are used you must quote the value. Only keys with names that match the pattern are refreshed.
Specifies a comma-separated list of volumes (block devices) which are associated with the secure AES key in the repository. Only those keys are refreshed, which are associated with the specified volumes. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. You can omit the device-mapper name; if it is specified then only those keys are listed that are associated with the specified volume and device-mapper name. You can use wildcards to specify the volumes and device-mapper names. When wildcards are used you must quote the value.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. Only keys with the specified volume type are refreshed. This option is only available if zkey has been compiled with LUKS2 support enabled.
Specifies the key type of the secure key. Possible values are CCA-AESDATA, CCA-AESCIPHER, and EP11-AES. Only keys with the specified key type are refreshed.
Also update the associated information, such as the textual description, associated volumes, volume type, and sector size, with the information stored in the key management system.
Do not check if the volume(s) associated with the secure key(s) to be refreshed are available, or are already associated with other secure keys in the repository. This option only has an effect when specified together with option --refresh-properties.

Options for the pvsecrets list command

List all protected virtualization (PV) secret types, not only those that can be used with zkey.
Show all protected virtualization (PV) secret IDs in hex, even if the ID contains only printable characters.
Type of the protected virtualization (PV) secret to list. If omitted, all secret types are listed. Possible values are: PLAIN-TEXT, AES-128, AES-192, AES-256, AES-XTS-128, AES-XTS-256, HMAC-SHA-256, HMAC-SHA-512, ECDSA-P256, ECDSA-P384, ECDSA-P521, EDDSA-ED25519, and EDDSA-ED448.
ID of the protected virtualization (PV) secret to list. The pvsecret ID is a 32 byte hex string, optionally prefixed by 0x. You can use the YAML file that was created when using the pvsecret create command for adding the protected virtualization secret: --pvsecret-id "$(yq .id YAML-FILE)". You might have to install the yq package first. Either the --pvsecret-id option or the --pvsecret-name option can be specified, but not both.
Name of the protected virtualization (PV) secret to list. You can use the YAML file that was created when using the pvsecret create command for adding the protected virtualization secret: --pvsecret-name "$(yq .name YAML-FILE)". You might have to install the yq package first. Either the --pvsecret-id option or the --pvsecret-name option can be specified, but not both.

Options for the pvsecrets import command

ID of the protected virtualization (PV) secret to import. The pvsecret ID is a 32 byte hex string, optionally prefixed by 0x. You can use the YAML file that was created when using the pvsecret create command for adding the protected virtualization secret: --pvsecret-id "$(yq .id YAML-FILE)". You might have to install the yq package first. Either the --pvsecret-id option or the --pvsecret-name option can be specified, but not both.
Name of the protected virtualization (PV) secret to import. You can use the YAML file that was created when using the pvsecret create command for adding the protected virtualization secret: --pvsecret-name "$(yq .name YAML-FILE)". You might have to install the yq package first. Either the --pvsecret-id option or the --pvsecret-name option can be specified, but not both. If the --pvsecret-name option is specified, then the --name option can be omitted. The name of the protected virtualization secret key object in the repository will then be the same as the pvsecret name.
Specifies the name of the protected virtualization secret key object in the key repository. If the --pvsecret-name option is specified, then the --name option can be omitted. The name of the protected virtualization secret in the repository will then be the same as the pvsecret name.
Specifies a textual description for the protected virtualization secret in the key repository.
Specifies a comma-separated list of volumes (block devices) which are associated with the protected virtualization secret in the repository. These volumes are to be encrypted using dm-crypt with the protected virtualization secret. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. A specific volume can only be associated with a single key.
Specifies the sector size in bytes used with dm-crypt. It must be a power of two and in the range of 512 to 4096 bytes. If omitted, the system default sector size is used.
Specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. If omitted, luks2 is used. This option is only available if zkey has been compiled with LUKS2 support enabled. If LUKS2 support is not enabled, the default volume type is plain.
Generate a dummy passphrase randomly and associate it with the protected virtualization secret used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance for the security of the volume(s), when a protected virtualization secret is used to encrypt the volume(s), and can therefore be stored insecurely inside the key repository. If for a certain usage the passphrase is of relevance for security, then do not use this option. This option can only be specified for keys with a volume type of luks2.
Set a dummy passphrase that is read from the specified file and associate it with the protected virtualization secret used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance for the security of the volume(s), when an protected virtualization secret is used to encrypt the volume(s), and can therefore be stored insecurely inside the key repository. If for a certain usage the passphrase is of relevance for security, then do not use this option. This option can only be specified for keys with a volume type of luks2.

General options

Displays additional information messages during processing.
Displays help text and exits.
Displays version information and exits.

EXAMPLES

Generates a random 256-bit secure AES key and stores it in file 'seckey.bin'.
Generates a random 128-bit secure AES key for the XTS cipher mode and stores it in file 'seckey.bin'.
Generates a secure AES key from the clear key in file 'clearkey.bin' and stores it in file 'seckey.bin'.
Generates a random 256-bit secure AES key and stores it in the secure key repository using the name 'seckey'.
--apqns 03.004c Generates a random 256-bit secure AES key 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 APQN '03.004c'.
--volume-type luks2 Generates a random 256-bit secure AES key 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.
Re-enciphers the secure key in file 'seckey.bin' which is currently enciphered with the master key in the OLD register with the master key in the CURRENT register, and replaces the secure key in file 'seckey.bin' with the re-enciphered key.
Re-enciphers the secure key in file 'seckey.bin' which is currently enciphered with the master key in the CURRENT register with the master key in the NEW register, and saves the re-enciphered secure key to file 'seckey2.bin'.
Re-enciphers the secure key 'seckey' in the secure key repository.
Re-enciphers all secure keys contained in the secure key repository that are associated with APQN '03.004c'.
Validates the secure key in file 'seckey.bin' and displays its attributes.
Validates the secure key 'seckey' in the secure key repository and displays its attributes.
Lists all secure keys in the secure key repository and displays its attributes.
Lists all secure keys in the secure key repository with names ending with 'key' and displays its attributes.
Changes the secure key 'seckey' in the secure key repository and adds volume '/dev/dasdc2' with device-mapper name 'encvol2' to the list of associated volumes of this secure key.
Changes the secure key 'seckey' in the secure key repository and removes APQN '03.004c' from the list of associated APQNs of this secure key.
Generates crypttab entries for all volumes that match the pattern '/dev/dasdc*'.
Generates cryptsetup commands for the volumes that uses the device-mapper name 'enc_dasd'.
Generates cryptsetup commands for all volumes of type luks2.

ENVIRONMENT

If $ZKEY_REPOSITORY is set, it specifies the location of the secure key repository. If it is not set, then the the default location of the secure key repository is /etc/zkey/repository.
If $ZKEY_KMS_PLUGINS is set, it specifies the name of the KMS plugin configuration file. If it is not set, then the default KMS plugin configuration file /etc/zkey/kms-plugins.conf is used.
February 2024 s390-tools