Re-enciphering LUKS2 volume keys

Edit online

If a new master key must be used to re-encipher a secure key used as a LUKS2 volume key, you can use the zkey-cryptsetup reencipher command to perform this task.

Before you begin

This task requires that a new CCA or EP11 master key has been set on the attached cryptographic coprocessors with the TKE. Using the zkey-cryptsetup utility for re-enciphering a LUKS2 volume key encrypted with a CCA master key requires the IBM® CCA host library (libcsulcca.so) to be installed. For re-enciphering a LUKS2 volume key encrypted with an EP11 AES secure key, zkey-cryptsetup requires the Linux® on Z Enterprise PKCS #11 (EP11) Support Program (EP11 host library) to be installed.

To obtain information about your current secure key (which is the same as the LUKS2 volume key), perform the procedure described in Validating a secure key used with a LUKS2 volume.

Note: You need to perform this procedure for all volumes encrypted with a secure LUKS2 volume key.

If the disks are encrypted with secure keys stored in the secure key repository, then you can use the following command to get a list of keys and their associated volumes that require re-encipherment when changing the master key of a specific APQN:

zkey list --apqns <apqn1,apqn2,...>

Procedure

Load the CCA key parts for a new AES master key or EP11 master key using the TKE.
Do not yet set the new master key active at this time.
Re-encipher the LUKS2 volume key.
The zkey-cryptsetup command automatically detects whether the secure volume key is enciphered with a master key from the OLD or from the CURRENT register and re-enciphers the secure volume key with the appropriate new master key in the NEW register. You can explicitly specify this processing using the options --from-old or --to-new. Detecting a master key from the OLD register is not possible for EP11 master keys.

In addition, re-enciphering a secure volume key can be performed in-place, or in staged mode.

Example:
```
# zkey-cryptsetup reencipher /dev/mapper/disk1 --staged 
Enter passphrase for '/dev/mapper/disk1': disk1pw
The secure volume key of device '/dev/mapper/disk1' is enciphered with the
CURRENT master key and is being re-enciphered with the NEW master key.
Staged re-enciphering is initiated for device '/dev/mapper/disk1'. After the NEW 
master key has been set to become the CURRENT master key, run 'zkey-cryptsetup
reencipher' with option '--complete' to complete the re-enciphering process.
 
```
Now set the new CCA or EP11 AES master key active.
Complete the re-enciphering:
```
# zkey-cryptsetup reencipher /dev/mapper/disk1 --complete
```
Note: If you used several key slots on your LUKS2 volume before, only the one for which you entered the passphrase is kept. All other key slots are removed during re-enciphering. You need to add them again using cryptsetup luksAddKey.
This applies for example, if you use additional key slots for automatic opening volumes at system startup.

For more information on staged re-enciphering of keys and the zkey-cryptsetup command, read both, Re-encipher a secure LUKS2 volume key and zkey-cryptsetup - Managing LUKS2 volume keys. In addition, you can also refer to the zkey-cryptsetup man page.
Reset the pbkdf option like follows:
```
--pbkdf argon2i --pbkdf-memory 32 --pbkdf-force-iterations 4
or
--pbkdf pbkdf2
```
This step is not required when using the zkey-cryptsetup tool from an s390-tools package upstream version 2.9.0 or later.
The re-enciphering process of the zkey-cryptsetup tool from an s390-tools package older than version 2.9.0 sets the value of option pbkdf of the key slot with the interactive passphrase to the default Argon2i password-based key derivation function (PBKDF), no matter which value you had set before.

Using the Argon2i key derivation function without further options may cause an out-of-memory error when opening a LUKS2 volume. To avoid such an error during automatic unlocking of the encrypted volume at system startup, use the shown options or use --pbkdf pbkdf2. For more information, read Out-of-memory errors when opening a LUKS2 volume.
```
# cryptsetup luksConvertKey --pbkdf argon2i --pbkdf-memory 32 --pbkdf-force-iterations 4 \ 
/dev/mapper/disk1
Enter passphrase for keyslot to be converted:
disk1pw
```