zkey - Managing secure keys

Edit online

Use the zkey command to generate, validate, and re-encipher secure AES keys for Crypto Express CCA and EP11 coprocessors.

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.

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, SC33-8411 available on the IBM Knowledge Center at www.ibm.com/support/knowledgecenter/linuxonibm/liaaf/lnz_r_lib.html.
The reencipher subcommand requires the CCA host library (libcsulcca.so) to be installed for secure keys of type CCA-AESDATA or CCA-AESCIPHER. This library is part of the CCA software package.

The reencipher subcommand requires the Linux® on Z Enterprise PKCS #11 (EP11) Support Program (EP11 host library) for secure keys of type EP11-AES 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.

Figure 1. zkey syntax - base syntax

where

subcommand

is described in the following sections:

Generating a secure key
Validating secure keys
Re-encipher secure keys
Import a secure key into the the secure key repository
Export a secure key from the secure key repository
List secure keys in the secure key repository
Delete secure keys from the secure key repository
Change the properties of secure keys in the secure key repository
Rename a secure key in the secure key repository
Copy a secure key in the secure key repository
Generate a crypttab entry for a volume
Generate a cryptsetup command for a volume
Convert an AES DATA key into an AES CIPHER key

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

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

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 thesecure 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 - reencipher a secure key or 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.

<secure_key_file>

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

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

-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 thethe secure key repository that are associated with AP queue 03.004c.
```
zkey reencipher --apqns 03.004c
```

Import a secure key into the 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 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. Describes the secure key.

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

-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 in the . Each AP queue association specifies an 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.

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.

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, or EP11-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
```

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.

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

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