Re-encipher a secure LUKS2 volume key

Use the zkey-cryptsetup reencipher command to re-encipher a secure LUKS2 volume key of a volume encrypted with LUKS2 and the PAES cipher.

A secure AES volume key must be re-enciphered when the AES master key of the cryptographic coprocessor in CCA or EP11 coprocessor mode changes. Such a coprocessor has three different registers to store master keys: the CURRENT, the OLD, and the NEW register, as described in Re-enciphering AES secure keys. Note that EP11 coprocessors do not contain an OLD register.

zkey-cryptsetup automatically detects whether the secure volume key is currently enciphered with the master key in the OLD register (not valid for EP11 secure keys, no OLD register on EP11 coprocessors) 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 (not valid for EP11 secure keys). 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. If for this case the NEW register does not contain a valid master key, then the re-encipher operation fails.

Re-enciphering a secure volume key of a volume encrypted with LUKS2 and the PAES cipher can be performed in-place, or in staged mode:

In-place

immediately replaces the secure volume key in the LUKS2 header of the encrypted volume with the re-enciphered secure volume key. Re- enciphering from OLD to CURRENT is performed in-place per default. You can use option --in-place to force an in-place re-enciphering for the CURRENT to NEW case. Be aware that an encrypted volume with a secure volume key that was re-enciphered in-place from CURRENT to NEW is no longer usable, until the new CCA or EP11 master key has been made the current one.

Staged mode

means that the re-enciphered secure volume key is stored in a separate (unbound) key slot in the LUKS2 header of the encrypted volume. Thus all key slots containing the current secure volume key are still valid at this point. Once the new CCA or EP11 master key has been set (made active), you must rerun the re-encipher command with option --complete to complete the staged re-enciphering. When completing the staged re-enciphering, the (unbound) key slot containing the re-enciphered secure volume key becomes the active key slot and, optionally, all key slots containing the old secure volume key are removed. Re-enciphering from CURRENT to NEW is performed in staged mode per default. You can use option --staged to force a staged re-enciphering for the OLD to CURRENT case.

The NEW register of a cryptographic coprocessor may contain a new master key to be set. This master key in the NEW register cannot be used until it is made the current master key. Use the --to-new option of the zkey-cryptsetup reencipher command to pro-actively re-encipher a secure key with the NEW master key before this key is made the CURRENT key.

Use the --from-old option to re-encipher a secure volume key that is currently enciphered with the master key in the OLD register with the master key in the CURRENT register.

When re-enciphering or setting LUKS2 volume keys using the zkey-cryptsetup reencipher command, you can specify the --batch-mode option to suppress confirmation questions. All confirmations when running the underlying cryptsetup commands are assumed to be answered with YES. This allows better automation of zkey-cryptsetup commands.

Examples:

To re-encipher the secure key of the encrypted volume /dev/mapper/disk1 in staged mode and complete it later:

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

# zkey-cryptsetup reencipher /dev/mapper/disk1 --complete

# zkey-cryptsetup reencipher /dev/mapper/disk1 --in-place --batch-mode