zkey - Managing secure keys

The zkey command is used in the context of a cryptographic domain of a Crypto Express adapter in CCA coprocessor mode or in EP11 mode. At least one domain must have an AES master key configured. Such a domain of a cryptographic coprocessor maintains three registers for master keys: The OLD, the NEW, and the CURRENT. In the following description, OLD, NEW, and CURRENT refer to the master key registers of the applicable domain.

Note: A cryptographic coprocessor configured in EP11 mode does not contain an OLD master key register.

You can either manage your keys as key files in the file system or use a secure key repository. You can set up the secure key repository with the environment variable ZKEY_REPOSITORY. The default repository is /etc/zkey/repository.

Terminology: The secure key repository is also referred to as zkey key repository.

Note: If multiple domains on potentially multiple CCA or EP11 coprocessors coprocessors are available, the zkey command may use any of those domains, and therefore, coprocessors.

Attention: Handle your cryptographic keys with care. The loss of a key can result in data loss.

Prerequisites

The zkey command requires access to a cryptographic domain that holds an AES master key.
The zkey command requires the pkey kernel module. For more information, see chapter Protected key device driver in Device Drivers, Features, and Commands.
For secure keys of type CCA-AESDATA or CCA-AESCIPHER, the reencipher subcommand requires the CCA host library (libcsulcca.so) to be installed. This library is part of the CCA software package.
For secure keys of type EP11-AES, the reencipher subcommand requires the Linux® on Z Enterprise PKCS #11 (EP11) Support Program (EP11 host library) to be installed.
To download the required packages, go to www.ibm.com/security/cryptocards and proceed to the software download page for your IBM® cryptographic coprocessor version.

For more information, read openCryptoki - An Open Source Implementation of PKCS #11.

Prerequisites for using extractable or exportable keys

To be used with dm-crypt (and the PAES kernel cipher), an EP11 secure key must be protected-key-extractable, that means, attribute CKA_IBM_PROTKEY_EXTRACTABLE must be set to TRUE (CK_TRUE). EP11 allows to also set attribute CKA_EXTRACTABLE to CK_TRUE for keys that are protected-key-extractable only when access control point XCP_CPB_ALLOW_COMBINED_EXTRACT is set to ON. 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, then the zkey utility issues an appropriate error message.

Ease the use of passphrases

The zkey utility is enhanced to store the (dummy) passphrase together with the key in the zkey key repository to ease administration of LUKS2 volumes encrypted with secure keys, starting with the upstream version 2.30.0 of the s390-tools package. That way, when the repository is backed up, or archived, also the (dummy) passphrases of the associated LUKS2 volumes are backed up or archived, and thus can not be forgotten. See the description of the --gen-dummy-passphrase and the --set-dummy-passphrase options for the relevant subcommands.

Handling EP11 extractable or CCA exportable keys

By default, secure keys of type CCA-AESCIPHER and EP11-AES are export-restricted when generated by the zkey generate command. 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, you can specify option --wrap-with-trusted to allow wrapping only with a trusted KEK. This option is only allowed when option --exportable is also specified.

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. Keys that are managed by an external key management system do not need to be transported to another system. Instead the keys can be retrieved by the zkey utility from the key management system on that other system via zkey kms import (see Enterprise Key Management for Pervasive Encryption of Data Volumes).

You can specify options --exportable and --wrap-with-trusted when generating keys to be stored in a file or in the secure key repository. You can also specify these options when generating a secure key from a clear key.

The zkey command base syntax

Figure 1. zkey syntax - base syntax

where

subcommand

is one of the following:

gen or generate, see Generating a secure key
val or validate, see Validating secure keys
re or reencipher, see Re-encipher secure keys
im or import, see Import a secure key into the secure key repository
ex or export, see Export a secure key from the secure key repository
li or list, see List secure keys in the secure key repository
rem or remove, see Delete secure keys from the secure key repository
ch or change, see Change the properties of secure keys in the secure key repository
ren or rename, see Rename a secure key in the secure key repository
co or copy, see Copy a secure key in the secure key repository
cryptt or crypttab, see Generate a crypttab entry for a volume
crypts or cryptsetup, see Generate a cryptsetup command for a volume
con or convert, see Convert an AES DATA key into an AES CIPHER key
pvsecret list and pvsecret import, see Handling retrievable secrets of an IBM Secure Execution for Linux guest

-V or --verbose

displays additional information during processing.

-h or --help

displays help information for the command. Specify zkey subcommand -h to get help for a subcommand.

-v or --version

displays the version number of zkey.

Generating a secure key

Figure 2. zkey syntax - generating a secure key

where

gen or generate

generates a new secure AES key either randomly within the cryptographic coprocessor, or from a clear AES key specified as input. You can store the key in a file or in the secure key repository.

Note: Retrievable secrets of type PVSECRET-AES cannot be generated, only imported.

-N <name> or --name <name>

specifies the name of the secure key. The key is generated into the secure key repository. The name can contain any of the following characters:

0-9 A-Z a-z ! @ # $ & ^ ~ ( ) = +

-t <volume-type> or --volume-type <volume-type>

Optional. Specifies the volume type of the associated volumes used with dm-crypt. Possible values are PLAIN or LUKS2 (not case-sensitive). 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.

-d <text> or --description <text>

Optional. Describes the secure key.

-l <volumes> or --volumes <volumes>

Optional. You can associate volumes with a key. Each volume association specifies the name of the block device (for example /dev/mapper/disk1) and the device mapper name separated by a colon. Separate multiple volume associations with a comma, for example:

-l /dev/mapper/disk1:enc-disk1,/dev/mapper/disk2:enc-disk2

-a <AP queues> or --apqns <AP queues>

Optional. You can associate AP queue numbers with a key. Each AP queue association specifies a device number and domain separated by a period. Separate multiple AP queue associations with a comma, for example:

-a 00.0005,00.001f,00.004d

When at least one APQN is specified, then the first one 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.

--no-apqn-check

Optional. Disable checking whether the specified APQNs are available and have the same master key. With this option, a currently non-existing APQN can be associated with a secure key. This is useful to associate APQNs that exist only on other systems, such as disaster recovery systems, but not on the current system. When generating keys, at least one of the specified APQNs must be available to generate the key.

-S <bytes> or --sector-size <bytes>

Optional. Specifies the sector size in bytes used with dm-crypt. It must be a power of two in the range 512 - 4096 bytes. The default sector size is 512 bytes.

<secure-key-file>

specifies the name of the file that holds the secure key if you are not using a repository.

-K <key-type> or --key-type <key-type>

Optional. Specifies the type of the secure key. To generate an AES DATA key, specify CCA-AESDATA, to generate an AES CIPHER key, specify CCA-AESCIPHER. To generate an EP11 AES secure key for use on cryptographic coprocessors configured in EP11 mode, specify EP11-AES. You cannot use key type PVSECRET-AES. If this parameter is omitted, then an AES DATA key (CCA-AESDATA) is generated as default.

This applies to both, keys stored in the secure key repository, as well as keys stored in a file outside of the secure key repository.

-k or --keybits <size>

specifies the size of the AES key to be generated in bits. Valid sizes are 128, 192, and 256 bits. Secure keys for use with the XTS cipher mode can only use keys of 128 or 256 bits. The default is 256 bits.

-x or --xts

generates a secure AES key for the XTS cipher mode. A secure AES key for the XTS cipher mode consist of two concatenated secure keys.

-c or --clearkey <clear-key-file>

specifies a file path that contains the clear AES key in binary form. If the --keybits option is omitted, the size of the specified file determines the size of the AES key. If the --keybits option is specified, the size of the specified file must match the specified key size. Valid file sizes are 16, 24, or 32 bytes, and for the XTS cipher mode 32 or 64 bytes.

--exportable

Generate a secure EP11 AES or CCA AES CIPHER key that is not export-restricted. Exportable (or extractable) keys can be exported by means of wrapping them with a key-encryption key (KEK). By default, keys of type CCA-AESCIPHER and EP11-AES are export-restricted, and thus can not be wrapped by a KEK. Keys of type CCA-AESDATA are always exportable, and can not be export-restricted.

--wrap-with-trusted

Generate a secure AES key that can only be wrapped with a trusted key-encryption key (KEK). This option is only valid for keys of type EP11-AES and only if option --exportable is also specified.

--gen-dummy-passphrase

For LUKS2 volumes only. Generate a random 16-byte passphrase and associate it with the secure AES key. Because the AES key’s security derives from the HSM and not from the passphrase, the dummy passphrase is non-critical and may be stored insecurely. Since the AES key ensures security, the passphrase can be stored insecurely in the secure key repository. This option is only allowed for secure keys contained in the secure key repository that are associated with a LUKS2 volume.

--set-dummy-passphrase

For LUKS2 volumes only. Read a dummy passphrase from the specified file and associates it with a secure AES key used to encrypt LUKS2 volumes. Because the AES key’s security derives from the HSM and not from the passphrase, the dummy passphrase is non-critical and may be stored insecurely. If, nevertheless, for a certain usage the passphrase is of relevance for security, then do not use this option.

This option is only allowed for secure keys contained in the secure key repository that are associated with a LUKS2 volume.

Examples

To generate a 256-bit secure AES DATA key and store it in file seckey.bin:
```
zkey generate seckey.bin
```
To generate a 128-bit secure AES CIPHER key for the XTS cipher mode and store it in file seckey.bin:
```
zkey generate seckey.bin --keybits 128 --xts -K CCA-AESCIPHER
```
To generate a secure AES DATA key from the clear key in file clearkey.bin and store it in file seckey.bin:
```
zkey generate seckey.bin --clearkey clearkey.bin
```
To generate a random 256-bit secure AES DATA key and store it in the secure key repository under the name seckey:
```
zkey generate --name seckey
 
```
To generate a random 256-bit secure AES DATA key, store it in the secure key repository under the name seckey, and associate it with block device /dev/mapper/disk1 and device-mapper name enc-disk1, and associate it with AP queue 03.004c:
```
zkey generate --name seckey --volumes /dev/mapper/disk1:enc-disk1 --apqns 03.004c
 
```

Validating secure keys

Figure 3. zkey syntax - validating a secure key or keys

where

val or validate: checks whether the specified file contains a valid secure key. It also displays the attributes of the secure key, such as key size, whether it is a secure key that can be used for XTS cipher mode, and the master key register with which the secure key is enciphered.
<secure-key-file>: specifies the name of the file that holds the secure key if you are not using the secure key repository.
-N <name> or --name <key name>: specifies the key name. You can validate a specific key by specifying its name, or you can use wildcards to match keys to be validated. If no key name is specified, all keys in the secure key repository are validated.
-a <AP queues> or --apqns <AP queues>: Optional. 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 secure key repository that match both patterns are validated.
--no-apqn-check: Optional. Disable checking whether the specified APQNs are available.

Examples

To validate the secure key in seckey.bin and display its attributes:
```
zkey validate seckey.bin
```
To validate the secure key seckey in the secure key repository and display its attributes.
```
zkey validate --name seckey
```

Re-encipher secure keys

Figure 4. zkey syntax - re-encipher secure keys

where

re or reencipher

re-enciphers 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 coprocessor changes.

Note: Retrievable secrets of type PVSECRET-AES do not need to be re-enciphered as they are not associated with a coprocessor.

-N <name> or --name <name>

specifies the key name. You can re-encipher a specific key by specifying its name, or you can use wildcards to match keys to be re-enciphered.

<secure_key_file>

specifies the name of the file that holds the secure key when you are not using the secure key repository.

-a <AP queues> or --apqns <AP queues>

Optional. Specifies one or more AP queues for keys in the secure key repository. All keys that are associated with the specified AP queues are re-enciphered. You can use wildcards. Separate multiple AP queues with a comma. If neither key name nor AP queue is specified, then all keys are re-enciphered. If both key name and AP queues are specified then only those keys that match both specifications are re-enciphered.

-i or --in-place

forces an in-place re-enciphering. This is the default for OLD to CURRENT.

-s or --staged

stores the key in a third file (<key-name>.renc) in the secure key repository. The key in <key-name>.skey is still valid. Once a new master key has been set, you must rerun the reencipher command with option --complete. This copies the file <key-name>.renc to <key-name>.skey and thus completes the staged re-enciphering. Re-enciphering from CURRENT to NEW is by default done in staged mode.

-p or --complete

completes a staged re-enciphering.

-n or --to-new

re-enciphers a secure key that is currently enciphered with the master key in the CURRENT register with the master key in the NEW register.

-o or --from-old

re-enciphers a secure key that is currently enciphered with the master key in the OLD register with the master key in the CURRENT register.

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

Note: This option is not available for secure keys of type EP11-AES, because an EP11 cryptographic coprocessor has only two registers to store master keys, CURRENT and NEW.

-f or --output <output_file>

specifies the name of the output file to which the re-enciphered secure key is written if you are not using the secure key repository. If this option is omitted, the re-enciphered secure key is replaced in the file that currently contains the secure key.

Examples

To re-encipher the secure key in seckey.bin, which is currently enciphered with the master key in the OLD register with the master key in the CURRENT register, and replace the secure key in seckey.bin with the re-enciphered key:
```
zkey reencipher seckey.bin --from-old
```
To re-encipher the secure key in seckey.bin, which is currently enciphered with the master key in the CURRENT register, with the master key in the NEW register, and save the re-enciphered secure key to seckey2.bin:
```
zkey reencipher seckey.bin --to-new --output seckey2.bin
```
To re-encipher the secure key seckey in the the secure key repository.
```
zkey reencipher --name seckey
```
Re-enciphers all secure keys contained in the secure key repository that are associated with AP queue 03.004c.
```
zkey reencipher --apqns 03.004c
```

Import a secure key into the secure key repository

Figure 5. zkey syntax - import a secure key into the repository

where:

im or import

imports a secure key into the secure key repository.

<secure_key_file>

specifies the name of the file that holds the secure key that you want to import.

-N <key_name> or --name <key_name>

specifies the name of the secure key.

-t <volume_type> or --volume-type <volume_type>

Optional. Specifies the volume type of the associated volumes used with dm-crypt. Possible values are PLAIN or LUKS2 (not case-sensitive). 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.

-d <description> or --description <description>

Optional. Describes the secure key.

-l <volumes> or --volumes <volumes>

Optional. You can associate volumes with a key. Each volume association specifies the name of the block device (for example /dev/mapper/disk1) and the device mapper name separated by a colon. Separate multiple volume associations with a comma; for example:

-l /dev/mapper/disk1:enc-disk1,/dev/mapper/disk2:enc-disk2

-a <AP queues> or --apqns <AP queues>

Optional. You can associate AP queue numbers with a key. Each AP queue association specifies a device number and domain separated by a period. Separate multiple AP queue associations with a comma; for example:

-a 00.0005,00.001f,00.004d

All specified APQNs must be online, unless option --no-apqn-check is specified.

--no-apqn-check

Optional. Do not check whether the specified APQNs are available. Use this option to associate APQNs with a secure AES key that are currently not available.

-S <bytes> or --sector-size <bytes>

Optional. Specifies the sector size in bytes used with dm-crypt. The value must be a power of two in the range 512 - 4096 bytes. The default sector size is 512 bytes.

--exportable

Allow to import a secure AES key that is not export-restricted. Exportable keys can be exported by means of wrapping them with a key-encryption key (KEK). By default, keys of type CCA-AESCIPHER and EP11-AES are export-restricted, and thus can not be wrapped by a KEK. Keys of type CCA-AESDATA are always exportable, and can not be export-restricted.

--gen-dummy-passphrase

For LUKS2 volumes only. Generate a random 16-byte passphrase and associate it with the secure AES key or with a retrievable secret key. Both types of AES keys are used to encrypt LUKS2 volumes. Because the AES key’s security derives from the HSM or ultravisor protection, and not from the passphrase, the dummy passphrase is non-critical and may be stored insecurely. Since the AES key ensures security, the passphrase can be stored insecurely in the secure key repository. This option is only allowed for secure keys contained in the secure key repository that are associated with a LUKS2 volume.

--set-dummy-passphrase

For LUKS2 volumes only. Read a dummy passphrase from the specified file and associates it with a secure AES key or with a retrievable secret key used to encrypt LUKS2 volumes. Because the AES key’s security derives from the HSM or ultravisor protection, and not from the passphrase, the dummy passphrase is non-critical and may be stored insecurely. If, nevertheless, for a certain usage the passphrase is of relevance for security, then do not use this option.

This option is only allowed for keys contained in the secure key repository that are associated with a LUKS2 volume.

Note: The zkey import command can also import CCA AES CIPHER secure keys and EP11 AES secure keys. When importing an AES CIPHER key, additional checks are performed on this key, such as a check of the history section of the secure key. If a potentially insecure setting is detected, you are prompted to confirm the import. Imported AES CIPHER keys are restricted for export in any way, regardless of the export setting of the imported keys. The only export that is kept allowed is the export to CPACF protected keys, so that these keys can be used with the PAES cipher.

For information about importing keys that are available in the ultravisor for an IBM Secure Execution guest (retrievable secrets), see Handling retrievable secrets of an IBM Secure Execution for Linux guest.

Export a secure key from the secure key repository

Figure 6. zkey syntax - export a secure key from the repository

where

ex or export: exports a key specified by name.
<secure_key_file>: specifies the name of the file that holds the secure key after you have exported it.
-N <name> or --name <name>: specifies the name of the secure key that you want to export.

List secure keys in the secure key repository

Figure 7. zkey syntax - list secure keys in the key repository

where

li or list: lists a key specified by name. You can use wildcards to match keys to be listed. If no name, volume, or AP queue is specified, all keys are listed.
-N <key_name> or --name <key_name>: Optional. Specifies the name of the secure key.
-t <volume_type> or --volume-type <volume_type>: Optional. Specifies the volume type of the associated volumes used with dm-crypt. Possible values are PLAIN orLUKS2 (not case-sensitive). Only keys with the specified volume type are listed. This option is only available if zkey has been compiled with LUKS2 support enabled.
-l <volumes> or --volumes <volumes>: Optional. Specifies one or more volumes and device mapper names associated with a key. Separate multiple volumes with a comma. All keys that are associated with the specified volumes are listed.
You can use wildcards for the volumes specification. If a device mapper name is specified as part of the volume association, then it is used as part of the filter. If no device mapper name is specified as part of a volume association, only the volume itself is used as filter.
-a <AP queues> or --apqns <AP queues>: Optional. Specifies one or more AP queues of crypto adapters. Separate multiple AP queues with a comma. All keys that are associated with the specified AP queues are listed. You can use wildcards for the AP queue specification.
-K <key type> or --key-type <key type>: Optional. Specifies the type of the secure keys to be listed. Valid values are CCA-AESDATA, CCA-AESCIPHER, EP11-AES, or PVSECRET-AES.

Examples

To list all secure keys in the secure key repository and display their attributes:
```
zkey list
```
To list all secure keys in the secure key repository with names ending with "key", and of type AES CIPHER keys:
```
zkey list --name *key -K CCA-AESCIPHER
```
To filter your secure keys in the secure key repository for EP11 AES secure keys:
```
zkey list -K EP11-AES
```

For information about listing keys that are available in the ultravisor for an IBM Secure Execution for Linux guest (retrievable secrets), see Handling retrievable secrets of an IBM Secure Execution for Linux guest.

Delete secure keys from the secure key repository

Figure 8. zkey syntax - delete secure keys from a key repository

where:

rem or remove: deletes a key specified by name.
-N <key_name> or --name <key_name>: Specifies the name of the secure key.
-F or --force: Optional. Does not prompt for confirmation of key removal.

Change the properties of secure keys in the secure key repository

Figure 9. zkey syntax - change the properties of secure keys in a key repository

where

ch or change

changes the description, volume association or AP queue association of a key specified by name.

-N <key_name> or --name <key_name>

Specifies the name of the secure key.

-t <volume_type> or --volume-type <volume_type>

Optional. Specifies the volume type of the associated volumes used with dm-crypt. Possible values are PLAIN orLUKS2 (not case-sensitive). 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.

-d <description> or --description <description>

Optional. Specifies a description of the secure key. If a description exists, it is overwritten.

-l <volumes> or --volumes <volumes>

Optional. Specifies one or more volumes and device mapper names associated with a key. Separate multiple volumes with a comma. All keys that are associated with the specified volumes are listed.

You can use add, delete, or overwrite volume specifications:

To add volumes to the current associations, prefix the list of volumes that are to be added with a plus sign (+).
To remove volumes from the current associations, prefix the list of volumes that are to be removed with a minus sign (-).
If neither minus nor plus is used, then the volume associations are set, overwriting any existing associations.

In one command, you can either add, delete, or set volume associations.

-a <AP queues> or --apqns <AP queues>

Optional. Specifies one or more AP queues of crypto adapters. Separate multiple AP queues with a comma.

You can use add, delete, or overwrite AP queue specifications:

To add AP queues to the current associations, prefix the list of volumes that are to be added with a plus sign (+).
To remove AP queues from the current associations, prefix the list of volumes that are to be removed with a minus sign (-).
To set AP queues, do not use neither minus nor plus sign. Then the AP queues associations are set, overwriting any existing associations.

In one command, you can either add, delete, or set AP queue associations.

All APQNs being added or set (replaced) must be online, unless option --no-apqn-check is specified.

Note: You cannot associate APQNs with a key that was imported from a retrievable secret. Such keys are of type PVSECRET-AES.

--no-apqn-check

Optional. Do not check whether the specified APQNs are available. Use this option to associate APQNs with a secure AES key that are currently not available.

-S <bytes> or --sector-size <bytes>

Optional. Specifies the sector size in bytes used with dm-crypt. The value must be a power of two in the range 512 - 4096 bytes. The default sector size is 512 bytes. If you specify 0, the default is used.

--gen-dummy-passphrase

For LUKS2 volumes only. Generate a random 16-byte passphrase and associate it with the secure AES key or with a retrievable secret key. Both types of AES keys are used to encrypt LUKS2 volumes. Because the AES key’s security derives from the HSM or ultravisor protection, and not from the passphrase, the dummy passphrase is non-critical and may be stored insecurely. Since the AES key ensures security, the passphrase can be stored insecurely in the secure key repository. This option is only allowed for secure keys contained in the secure key repository that are associated with a LUKS2 volume.

--set-dummy-passphrase

For LUKS2 volumes only. Read a dummy passphrase from the specified file and associates it with a secure AES key or with a retrievable secret key used to encrypt LUKS2 volumes. Because the AES key’s security derives from the HSM or ultravisor protection, and not from the passphrase, the dummy passphrase is non-critical and may be stored insecurely. If, nevertheless, for a certain usage the passphrase is of relevance for security, then do not use this option.

This option is only allowed for keys contained in the secure key repository that are associated with a LUKS2 volume.

--remove-dummy-passphrase

Remove the dummy passphrase associated with LUKS2 volumes. By default, a confirmation prompt is shown. Use option --force to bypass confirmation. This option applies only to secure keys in the secure key repository.

-F or --force

Remove the dummy passphrase without a confirmation prompt. Only valid with --remove-dummy-passphrase for secure keys in the secure key repository.

Examples

To change the secure key seckey in the secure key repository and add volume /dev/mapper/disk2 with device-mapper name enc-disk2 to the list of associated volumes of this secure key:
```
zkey change --name seckey --volumes +/dev/mapper/disk2:enc-disk2 
```
To change the secure key seckey in the secure key repository and remove AP queue 03.004c from the list of associated AP queues:
```
zkey change --name seckey --apqns -03.004c
```

Rename a secure key in the secure key repository

Figure 10. zkey syntax - rename a secure key in a key repository

where

ren or rename: renames a key specified by name.
-N <old_key_name> or --name <old_key_name>: specifies the name of the secure key.
-w <new_key_name> or --newname <new_key_name>: specifies the name to which the secure key is renamed.

Copy a secure key in the secure key repository

Figure 11. zkey syntax - copy a secure key in the key repository

where:

co or copy

copies a key specified by name. Volume associations are not copied.

-N <key_name> or --name <key_name>

specifies the name of the secure key.

-w <new_key_name> or --newname <new_key_name>

specifies the name to which the secure key is copied.

-l <volumes> or --volumes <volumes>

Optional. You can associate volumes with the copied key. Each volume association specifies the name of the block device (for example /dev/mapper/disk1) and the device mapper name separated by a colon. Separate multiple volume associations with a comma; for example:

-l /dev/mapper/disk1:enc-disk1,/dev/mapper/disk2:enc-disk2

Generate a crypttab entry for a volume

Figure 12. zkey syntax - generate a crypttab entry for a volume

where

cryptt or crypttab: generates crypttab entries for one or more volumes and any device mapper names. crypttab auto-mounts encrypted volumes during system start-up. If no volumes are specified, crypttab entries are generated for all volumes associated with a key.
-t <volume_type> or --volume-type <volume_type>: Optional. Specifies the volume type of the associated volumes used with dm-crypt. Possible values are PLAIN orLUKS2 (not case-sensitive). 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.
-l <volumes> or --volumes <volumes>: Optional. Specifies one or more volumes and device mapper names associated with a key. Separate multiple volumes with a comma. All keys that are associated with the specified volumes are listed.
You can use wildcards for the volumes association. If a device mapper name is specified as part of the volume association, then it is used as part of the filter. If no device mapper name is specified as part of a volume association, then only the volume itself is used as filter.
--key-file <file_name>: 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. The crypttab entries are generated for LUKS2 volumes based on this option, which is only available if zkey has been compiled with LUKS2 support enabled.
--keyfile-offset <bytes>: 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. The crypttab entries are generated for LUKS2 volumes based on this option, which is only available if zkey has been compiled with LUKS2 support enabled. Not all distributions support the keyfile-offset option in crypttab entries.
--keyfile-size <bytes>: 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. The crypttab entries are generated for LUKS2 volumes based on this option, which is only available if zkey has been compiled with LUKS2 support enabled. Not all distributions support the keyfile-size option in crypttab entries.
--tries <number>: 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.

Example

To generate crypttab entries for all volumes that match the pattern /dev/mapper/disk*:

zkey crypttab --volumes /dev/mapper/disk*

Generate a cryptsetup command for a volume

Figure 13. zkey syntax - generate a cryptsetup command for a volume

where

crypts or cryptsetup: generates cryptsetup commands for one or more volumes and device mapper names. cryptsetup commands mount the encrypted volumes. If no volumes are specified, cryptsetup commands are generated for all volumes associated with a key in the secure key repository.
-t <volume_type> or --volume-type <volume_type>: Optional. Specifies the volume type of the associated volumes used with dm-crypt. Possible values are PLAIN or LUKS2 (not case-sensitive). 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.
-l <volumes> or --volumes <volumes>: Optional. Specifies one or more volumes and device mapper names associated with a key. Separate multiple volumes with a comma. All keys that are associated with the specified volumes are listed.
You can use wildcards for the volumes association. If a device mapper name is specified as part of the volume association, it is used as part of the filter. If no device mapper name is specified as part of a volume association, only the volume itself is used as filter.
--open: Optional. 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.
--format: Optional. Limits the generated commands to only generate cryptsetup luksFormat commands for LUKS2 volumes (without generating cryptsetup luksOpen commands), and skip plain mode volumes. 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.
--key-file <file_name>: 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.
--keyfile-offset <bytes>: 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.
--keyfile-size <bytes>: 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.
--tries <number>: 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.
-q or --batch-mode: Optional. If specified, this option suppresses confirmation questions in the generated cryptsetup command(s) by assuming an implicit confirmation.
-r or --run: Optional. Executes the cryptsetup commands. If one command fails, execution stops.

Example

To generate cryptsetup commands for the volumes that use the device-mapper name enc-disk1:

zkey cryptsetup --volumes *:enc-disk1

Note: For LUKS2 volumes, the generated cryptsetup luksFormat contains options

--pbkdf argon2i --pbkdf-memory 32 --pbkdf-force-iterations 4

to set Argon2i as password based key derivation function. If this leads to out-of-memory errors when multiple encrypted volumes are unlocked automatically at boot through /etc/crypttab, apply one of the methods described in Out-of-memory errors when opening a LUKS2 volume.

Note: For LUKS2 volumes, the generated cryptsetup luksFormat contains option --pbkdf pbkdf2 to set PBKDF2 as password based key derivation function. LUKS2 volumes typically default to Argon2i as password based key derivation function, but this may cause out-of-memory errors when multiple encrypted volumes are unlocked automatically at boot through /etc/crypttab. 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.

Convert an AES DATA key into an AES CIPHER key

Figure 14. zkey convert - convert an AES DATA key into an AES CIPHER key

where

con or convert: converts an existing secure AES DATA key that is either contained in a secure key file or is stored in the secure key repository into an AES CIPHER key. The reverse direction is not possible.
-N <name> or --name <name>: specifies the name of the secure key in the secure key repository that is to be converted.

-K <key_type> or --key-type <key_type>: specifies the type of the key to which the secure key is to be converted. You can only convert AES DATA keys into AES CIPHER keys. So the only possible value is CCA-AESCIPHER.
--no-apqn-check: Optional. Specifies that no check should be performed whether the associated APQNs are available.
--exportable: Convert to a secure AES key that is not export-restricted. Exportable keys can be exported by means of wrapping them with a key-encryption key (KEK).
-F or --force: Optional. Specifies to not prompt for a confirmation when converting a key.

Example

Convert an AES DATA key to an AES CIPHER key:

zkey convert --name sec_data_key -K CCA-AESCIPHER

Additional examples for zkey generate

Generate a secure key of length 256 bit from a random clear key and store it in file securekey.bin:
```
zkey generate securekey.bin --keybits 256
```
Generate a secure AES CIPHER key from a binary clear key input file and store it in file securekey.bin:
```
zkey generate securekey.bin --clearkey clearkey.bin -K CCA-AESCIPHER
```
If you want to securely erase the clear key, you can issue the command:
```
shred -u clearkey.bin
```
Generate a secure key of length 256 bit for XTS cipher mode and store it in file securextskey.bin
```
zkey generate securextskey.bin --keybits 256 --xts
```