Recovering encrypted volumes with a secure key from the repository

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

1. 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
           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.
2. 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.
3. Reset the pbkdf option to use 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 zkey-cryptsetup 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.

   As described in Out-of-memory errors when opening a LUKS2 volume, the use of the Argon2i key derivation function 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, change the value of option pbkdf to use the PBKDF2 key derivation function:

   
   # cryptsetup luksConvertKey --pbkdf pbkdf2 /dev/mapper/disk<n>
   Enter passphrase for keyslot to be converted:
   disk<n>pw