Converting a LUKS2 volume from encryption with a clear key to a retrievable secret or a secure key

Edit online

You can convert any LUKS2 volume that is encrypted with a clear key to use a secure key or a retrievable secret for encryption. Especially, when setting up a new IBM® Secure Execution for Linux® guest (IBM SEL guest), you can convert a volume that uses clear-key cryptography to use a retrievable secret.

Before you begin

Attention: Take a LUKS2 header backup using cryptsetup luksHeaderBackup before converting a volume. The volume might not be recoverable after a failed conversion. If you have a LUKS header backup, then you can restore the volume using cryptsetup luksHeaderRestore.

About this task

You can convert any LUKS2 volumes currently using a clear key to start using a secure key or protected key derived from a retrievable secret. The typical use case, however, is that you may want to set up an IBM SEL guest, where the encrypted disk has been created on an architecture other than z/Architecture and therefore uses clear-key cryptography. On the first boot of such a guest, you can convert this encrypted disk to use an equivalent retrievable secret key or secure key using the PAES cipher.

With the described feature, the effective key (the clear key) remains the same, but just changes the format. Therefore, such a conversion does not require re-encryption of the volume. Only the LUKS2 header needs to be changed to contain the new key format, and the new cipher. After a successful conversion, your data is now protected more securely.

For this task, you can use the zkey-cryptsetup convert subcommand as described in detail in zkey-cryptsetup - Managing LUKS2 volume keys or in the zkey-cryptsetup man page.

Note: The zkey-cryptsetup convert command ensures that all the other settings stay the same, especially the cipher mode and initialization vector (IV) generation algorithm must stay the same. The PAES cipher only supports the plain64 IV generation algorithm. So only disks using plain64 can be converted. The cryptsetup luksFormat command defaults to aes-xts cipher mode with plain64, but if aes-cbc cipher mode is used, then the IV generation algorithm essiv:sha256 is typically used.

In the following procedure, steps 1 and 2 are performed outside the IBM SEL guest and steps 3 through 7 are performed on the IBM SEL guest.

Procedure

In this scenario, assume that the clear key for the volume is known and was formatted with the following command:
```
cryptsetup luksFormat --volume-key-file <clear-aes-xts-key> ...
```
Create a corresponding add-secret request for a retrievable secret with the name specified in retrievable <secret_name> on a trusted Linux system with the clear key as input.
```
pvsecret create --output <output-file> --host-key-document <host-key-document>  \ 
                --hdr <se-header> retrievable <secret_name> --type aes-xts \
                --secret <clear-aes-xts-key> [–extension-secret <ext_secret_file>]
```
Parameter <output_file> contains the created add-secret request.

In addition, this command produces a file of type YAML, <secret_name>.yaml in this scenario, together with the <output-file>. This file contains the secretID which you need in step 5 to import the secret into the zkey key repository.

The complete syntax and use of the pvsecret command is described in Introducing IBM Secure Execution for Linux, SC34-7721.
Issue a corresponding add-secret request to add the secret into the ultravisor of the IBM SEL guest.
```
pvsecret add <output_file>
```
In parameter <output_file>, specify the file that was generated in step 2. This file contains all required information for the add-secret request.

The created secret is now a retrievable secret. When running in an IBM SEL guest, it can access the same effective key (clear key) with which the LUKS2 volume has been encrypted.
Optional: Issue a zkey pvsecret list command to obtain the secretID of the created retrievable secret.
```
zkey pvsecret list
```
Import the retrievable secret into the zkey key repository.
```
zkey pvsecret import --pvsecret-id <hex_ID> --name <key_name>
```
You specify the secret's ID and a new name used to identify this key (or secret) in the zkey key repository.

You have two possibilities to obtain the ID required for this command:
- In file <secret_name>.yaml generated in step 2, you find the secretID required for this step in a form similar to the following example:
```
... 
name: <secret_name>
id: 0x09ac24ffd3d735ed2ab7954822c36316f42df92c6868bee228fb6d051ff975bd
 
```
- You can see the IDs of all existing secrets in the list output from step 4.
For the key conversion performed in step 7, you need to retrieve the name and the path of the key file as stored in the zkey key repository. Issue a zkey list command similar to the following:
```
zkey list --name <key_name>
```
The output of this command shows a line with the path and file name that you will need in the next step, like for example,
```
zkey list --name <key_name>
...
...
Key file name : /etc/zkey/repository/<key_name>
...
```
.
Continue with a command similar to the following to convert the specified LUKS2 volume to use the clear key referenced by the created retrievable secret from the zkey key repository:
```
zkey-cryptsetup convert <volume> --volume-key-file <file_path_and_key_name>
```
where
- <volume> specifies the volume for which you want to convert the volume key type.
- --volume-key-file specifies the file path and file name of the secret in the zkey key repository from which the derived protected key with the original clear key as the effective key, should be used by the volume as the new volume key. For example, if you specify --name volume1_secret in the command from step 5, you need to specify --volume-key-file /etc/zkey/repository/volume1_secret.skey.

Results

From now on, the specified LUKS2 volume is encrypted using a protected key derived from the retrievable secret which in turn is referencing the originally known clear key.

What to do next

You can imagine of other scenarios where the clear key of the original LUKS2 volume is not known. In this case, you can use the luksDump option to first export the volume key into a binary file (<clear-key-file> in our example) by using a command similar to the following:

# cryptsetup luksDump /dev/mapper/disk<n> --dump-master-key \
--master-key-file <clear-key-file>

Then you can continue with step 2 from the described procedure and create a secret from the dumped clear key.

In an other scenario, you may prefer to convert your original clear key into a secure key (of one of the available zkey key types CCA-AESDATA, CCA-AESCIPHER, EP11-AES). Use a different command in step 2 to generate and store a secure key from your known clear key in the zkey key repository:

zkey generate --name <key_name> --clearkey <clear-aes-key> ....

Continue with optionally step 6 and then step 7 to complete the conversion.