Generating AES secure keys

You can generate a secure key in the secure key repository using the zkey generate command with the --name option.

You can specify additional information, such as a textual description of the key. You can associate a secure key with one or multiple cryptographic coprocessors (APQNs) that are set up with the same CCA AES or EP11 AES 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.

Example:

# zkey generate --name secure_xtskey1 --keybits 256 --xts \
--description "This is our secure key in a repository" \
--volumes /dev/mapper/disk1:enc-disk1 --volume-type LUKS2 \
--apqns 03.0039,04.0039 --sector-size 4096

With parameter -K or --keytype, you can also specify a key type for the generated secure key. Valid values are CCA-AESDATA to generate AES DATA keys, or CCA-AESCIPHER to generate an AES CIPHER key. To generate an EP11 AES secure key for use on CEX7S or later cryptographic coprocessors configured in EP11 mode (CEX7P), specify key type EP11-AES.

Note: Linux™ allows hot-plugging of cryptographic coprocessors (APQNs). You might need to update the APQN associations with the zkey change command when an APQN had been added to or removed from the Linux instance.

The zkey tool checks, whether the master key is the same for all of the APQNs that are to be associated with a secure key during creation, or for all APQNs that are involved in a modification of a secure key. In cases, where no APQNs are associated with the generation or validation of a secure key (either outside or within the secure key repository), all APQNs available on the system are checked.

Warnings are issued if the APQNs do not fulfill the requirements to ensure that all APQNs have the same master key. In case of inconsistencies, a table of all associated APQNs with its master key verification patterns is displayed, together with warning or information messages, for example:

# zkey gen -N sec-aescipher -K CCA-AESCIPHER --apqns 02.001a,05.001a,06.001a
WARNING: APQN 02.001a: The card level is less than CEX6n.
WARNING: APQN 02.001a: No master key is set.
WARNING: Not all APQNs have the same master key or fulfill the requirements.

CARD.DOMAIN NEW MK           CURRENT MK       OLD MK           TYPE
---------------------------------------------------------------------
02.001a     -                -                -                CEX5C
05.001a     -                26d69731a66f4255 -                CEX6C
06.001a     -                c8af2f4873a65bd5 78410337dcb0061a CEX6C 
zkey: Your master key setup is improper

Warning messages normally prevent the generation or validation of master keys, while information messages allow the desired action.

Starting with CEX7P cryptographic coprocessors, you can generate an EP11 secure key, for example:

zkey gen -N sec-ep11-key -K EP11-AES -a 0a.0036,0b.0036 --xts