Replacing with a different master key

Edit online

In this scenario, the old cryptographic coprocessor still exists. All the secure keys generated on this coprocessor were generated from random keys.

Before you begin

As an alternative to the procedure described here, you can create a new encrypted volume and migrate the data there (see Migrating to an encrypted LVM physical volume or Migrating data to a new encrypted volume.

Important: If you use the approach described in this task, be sure to have a backup of the data on your volume in case the system crashes or a media error occurs during the re-encryption. In contrast to the mentioned alternatives, this re-encryption works on the volume in-place.

Procedure

Generate a new secure key on the new cryptographic coprocessor using zkey generate.
Store the new secure key in the secure key repository.
To generate a secure key on a specific APQN, use option --apqns with the zkey generate command and specify the desired APQN. This is only possible when generating secure keys in the secure key repository. For example, enter:
```
# zkey generate --name new_secure_xtskey --keybits 256 --xts \
--apqns <card.domain>
```
Because the new secure key now also contains a new effective key, a next step for re-encrypting is required.
Use the cryptsetup-reencrypt command to re-encipher all LUKS2 volumes that use the old secure key, with the new secure key from the secure key repository.
The new LUKS2 volume key is stored in the LUKS2 header of the volumes at the end of the re-encryption.
For example, enter:
```
# cryptsetup reencrypt /dev/mapper/disk<n>  \
  --new-volume-key-file '/etc/zkey/repository/new_secure_xtskey.skey' \
  --new-key-size 1024   --cipher paes-xts-plain64 --pbkdf argon2i     \
  --pbkdf-memory 32 --pbkdf-force-iterations 4 /dev/loop0
```
You can retrieve information about the just-created secure key file using the zkey list command. To limit the returned list to the desired secure key, use option --name to specify the secure key name. You find the secure key file name indicated by: Key file name (see Listing AES secure keys contained in the secure key repository).
Note: The sample is shown for the LUKS2 online reencryption feature version 2.8.0 or later. Previous versions need to use parameters --volume-key-file and --key-size instead of --new-volume-key-file and --new-key-size.
Important: Ensure that you have a backup copy of the volume that you want to re-encrypt. In case the system crashes or a media error occurs during re-encryption, your original data might be destroyed.
Set the verification pattern into the LUKS2 header using the zkey-cryptsetup command.
Issue a command similar to the following:
```
# zkey-cryptsetup setvp /dev/mapper/disk<n>
```
Remove the old cryptographic coprocessor and start using the new one.
If you previously stored the old secure key in the secure key repository, remove it now and associate the new secure key with the re-encrypted volume. For example, enter:
```
# zkey remove --name old_secure_xtskey
# zkey change --name new_secure_xtskey --volumes /dev/mapper/disk<n>:enc-disk<n> \
   --volume-type LUKS2 --sector-size 4096
```
Note: Ensure that the sector size for encryption or decryption of the volume is the same for the old and the new secure key. The example assumes that a sector size of 4096 bytes was used for encrypting or decrypting the volume with both the old and the new secure key.
For details see Removing AES secure keys and Changing AES secure keys.