Setting up an encrypted swap disk

You can use a volatile protected key generated by the pkey device driver to encrypt a swap disk.

Before you begin

The pkey kernel module requires permission for the AES key import functions to generate random protected keys. To grant this permission, go to the security settings of the applicable LPAR on the Hardware Management Console (HMC). In the CPACF Key Management Operations section, select the Permit AES Key import functions option. For z/VM® guests, the LPAR in which the hypervisor runs requires this option.

About this task

Because swap disks are discarded on reboot, volatile encryption keys are an option. You can generate volatile protected keys or secure keys from random data.

Important: Use a protected key based on random data only for cases where the key is not needed after a reboot. In particular, do not use such a key with:

KVM guest migration
z/VM live guest relocation in a single system image (SSI)
Suspend and resume

Procedure

Add an entry to /etc/crypttab.
To encrypt the swap device using a protected key, the entry must point to one of the sysfs attributes within the /sys/devices/virtual/misc/pkey/protkey/ directory. Use the attribute for the required key type (see Encrypting swap disks with protected keys).
For example:
```
# <name>   <device>            <password>                                                  <options>
swap_disk  /dev/mapper/disk99  /sys/devices/virtual/misc/pkey/protkey/protkey_aes_256_xts  swap,\
                                                                                           cipher=paes-xts-plain64,\
                                                                                           size=1280
```
The entry must be all in one line without continuation characters.
The swap option causes an mkswap command to be performed after the dm-crypt volume is set up.
Tip: Consider adding the sector-size=4096 option to increase the performance of dm-crypt encrypted disks with large block sizes.

Add an entry to /etc/fstab to use the device-mapper device named swap_disk as swap device:

For example:

# <filesystem>           <dir>      <type>      <options>      <dump>       <pass>
/dev/mapper/swap_disk    none       swap        defaults       0            0

Ensure that the pkey kernel module is loaded during system startup before /etc/crypttab is evaluated.
Ensure that a configuration file such as pkey.conf or modules.conf is in the .../modules-load.d/ directory. The configuration file must contain:
```
pkey
```
The .conf file(s) in .../modules-load.d/ contain the modules to be loaded early during startup, before the swap disk is initiated.

Results

During system startup, /etc/crypttab is evaluated, and a dm-crypt device is set up in plain mode as a swap device, using an AES protected key in XTS cipher mode. The random protected AES key is read from /sys/devices/virtual/misc/pkey/protkey/protkey_aes_256_xts. Its size is 2x80 bytes, which is 1280 bits.

The swap option causes that an mkswap is performed after the dm-crypt volume has been set up. The entry in /etc/fstab then causes the device-mapper device named swap_disk to be used as swap device.

Linux™ now runs with a swap device that is encrypted with a protected key.

What to do next

For reasons of security, you might consider to use a secure key instead of a protected key for encrypting swap disks. In such a case, you can generate a new random secure key from a cryptographic coprocessor using another set of sysfs attributes. You do not need to store and manage the secure key within the secure key repository, because you want to generate a new secure key at boot time, that is, each time you use a new swap disk.

A new random secure key is generated by a cryptographic coprocessor when reading from the ccadata_aes_256_xts attribute in the /sys/devices/virtual/misc/pkey/ccdata/ directory.

Add an entry to /etc/crypttab, similar to the one for protected keys, but now using a sysfs attribute from the .../ccadata/ directory.

# <name>   <device>            <password>                                                  <options>
swap_disk  /dev/mapper/disk99  /sys/devices/virtual/misc/pkey/ccadata/ccadata_aes_256_xts  swap,\
                                                                                           cipher=paes-xts-plain64,\
                                                                                           size=1024

The required entry to /etc/fstab is the same as for protected keys.