Recovering encrypted volumes with a secure key from the repository

Edit online

Read about the procedure how to recover encrypted data from a volume whose volume key is no longer valid (for example, if the volume has been archived a long time ago).

About this task

Recovering a secure key encrypted partition whose volume key is no longer valid is only possible if a valid copy of this key is available in the secure key repository. This copy of the secure key must have been re-enciphered in the repository each time the master key changed on the cryptographic coprocessor.

Procedure

Optional: Ensure that the secure key in the repository matches the volume key in the LUKS2 header.

This action is only possible if a verification pattern was previously set into the LUKS2 header. To check, enter the following commands and compare the verification patterns. The zkey-cryptsetup validate command checks the validity of the volume key on the volume and displays its verification pattern. The zkey validate command checks the validity of the specified secure key in the repository and also displays its verification pattern.

# zkey-cryptsetup validate /dev/mapper/disk<n>
Enter passphrase for '/dev/mapper/disk<n>': disk<n>pw
Validation of secure volume key of device '/dev/mapper/disk<n>':
  Status:                Invalid
  Secure key size:       272 bytes
  XTS type key:          Yes
  Key type:              CCA-AESCIPHER  
  Clear key size:        (unknown)
  Enciphered with:       (unknown) (MKVP: 880f72e3759217e7)
  Verification pattern:  477a8608f06743569e2c62fc5fe00085
                         08b18a80d7616094eceaa746be4a2edd
 
ATTENTION: The secure volume key is not valid. 

# zkey validate --name <name_of_key>
Key                          : <name_of_key>                                   
-------------------------------------------------------------------------------------
        Status               : Valid
        Description          : 
        Secure key size      : 272 bytes
        Clear key size       : 512 bits
        XTS type key         : Yes
        Key type:              CCA-AESCIPHER
        Enciphered with      : CURRENT master key (MKVP: 26d69731a66f4255)
        Volumes              : /dev/mapper/disk<n>:enc-disk<n>
        APQNs                : 03.0039
                               04.0039
        Key file name        : /etc/zkey/repository/<name_of_key>.skey
        Sector size          : (system default)
        Volume type          : LUKS2
        Verification pattern : 477a8608f06743569e2c62fc5fe00085
                               08b18a80d7616094eceaa746be4a2edd
        KMS                  : (local)
        KMS key label        : (local)
        Dummy passphrase     : (none)
        Created              : 2018-08-21 17:19:53
        Changed              : (never)
        Re-enciphered        : (never)

If you omit this step, and the keys mismatch, the zkey-cryptsetup setkey from step 2 will reject to set the key, provided that the verification pattern is available in the LUKS2 header.

Set the secure key from the secure key repository as the new volume key.
Enter the following command:
```
# zkey-cryptsetup setkey /dev/mapper/disk<n> \ 
--master-key-file /etc/zkey/repository/<name_of_key>.skey
Enter passphrase for '/dev/mapper/disk<n>': disk<n>pw
```
The verification pattern is used to ensure that the new volume key contains the same effective key as the old volume key. If no verification pattern is available, then you are prompted to confirm that the specified secure key is the correct one.
Important: If you set an incorrect secure key you will lose all the data on the encrypted volume.
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.

Setting a new LUKS2 volume key with 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/disk<n>
Enter passphrase for keyslot to be converted:
disk<n>pw
 
```