Encrypt a Block Storage device with LUKS

Block Storage encryption at rest uses encryption keys that UpCloud generates and manages. To keep the encryption keys under your own control, encrypt the storage device inside your Linux Cloud Server with LUKS (Linux Unified Key Setup). The data is encrypted before it is written to the storage device, and only someone with your passphrase or key file can read it.

You can use LUKS on its own or together with Block Storage encryption at rest.

Before you begin

• Add a separate storage device for the encrypted data. This guide encrypts an additional storage device attached to your server, not the device the operating system runs from, so the operating system keeps running as before. To add a device to your server, see Adding and removing storage devices.
• The device you encrypt must be empty. Encrypting a device with LUKS erases everything on that device. To encrypt existing data, encrypt a new device and copy the data over.
• Keep your passphrase safe. UpCloud has no access to your passphrases or key files and cannot recover the data if you lose them. Store your passphrase, and later your header backup, outside the server.

The examples use the storage device /dev/vdb, the name data for the unlocked device, and the mount point /mnt/data. Replace them with your own values.

1. Install cryptsetup

sudo apt install cryptsetup

sudo apt install cryptsetup

sudo apt install systemd-cryptsetup

sudo dnf install cryptsetup

2. Find the storage device

List the storage devices attached to the server:

lsblk

NAME   MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
vda    253:0    0  25G  0 disk
├─vda1 253:1    0   1M  0 part
└─vda2 253:2    0  25G  0 part /
vdb    253:16   0  10G  0 disk

The empty device has no partitions and no mount point, like vdb in the example above. The device mounted at /, vda in the example, holds the operating system. Don't use it in the following steps.

3. Encrypt the device

Encrypt the device with LUKS:

sudo cryptsetup luksFormat /dev/vdb

Type YES in capital letters to confirm, then enter and verify a passphrase:

WARNING!
========
This will overwrite data on /dev/vdb irrevocably.

Are you sure? (Type 'yes' in capital letters): YES
Enter passphrase for /dev/vdb:
Verify passphrase:

The device is now encrypted with LUKS2, using AES in XTS mode with a 512-bit key. You can check the details with sudo cryptsetup luksDump /dev/vdb.

4. Unlock, format, and mount the device

1. Unlock the device. Enter the passphrase when prompted:

   sudo cryptsetup open /dev/vdb data

   The unlocked device is available at /dev/mapper/data.

2. Create a filesystem on the unlocked device:

   sudo mkfs.ext4 /dev/mapper/data

3. Create a mount point and mount the device:

   sudo mkdir -p /mnt/data
   sudo mount /dev/mapper/data /mnt/data

4. Check the result:

   lsblk /dev/vdb

   NAME   MAJ:MIN RM SIZE RO TYPE  MOUNTPOINTS
   vdb    253:16   0  10G  0 disk
   └─data 252:0    0  10G  0 crypt /mnt/data

Anything you write to /mnt/data is now encrypted on the storage device.

5. Unlock the device after a restart

The device is locked again whenever the server restarts. Choose how to unlock it:

• Unlock manually: you enter the passphrase after each restart. The key never leaves your hands, but the data is unavailable until you unlock it.
• Unlock automatically with a key file: the server unlocks the device at boot using a key file stored on the OS storage device. Anyone with access to the OS storage device, including its backups, can unlock the data device too.

Unlock manually

1. Find the UUID of the encrypted device:

   sudo blkid /dev/vdb

   /dev/vdb: UUID="354d8ba8-7c36-4fd0-a64c-8fc2e36818fb" TYPE="crypto_LUKS"

2. Add the following line to /etc/fstab. The noauto option keeps the server from trying to mount the device at boot:

   /dev/mapper/data /mnt/data ext4 defaults,noauto 0 0

3. After each restart, unlock and mount the device. Replace the UUID with your own:

   sudo cryptsetup open /dev/disk/by-uuid/354d8ba8-7c36-4fd0-a64c-8fc2e36818fb data
   sudo mount /mnt/data

Using the UUID instead of /dev/vdb makes sure you unlock the right device even if the device names change.

Unlock automatically with a key file

1. Create a key file of random data that only root can read:

   sudo mkdir -m 700 /etc/luks-keys
   sudo dd if=/dev/urandom of=/etc/luks-keys/data.key bs=512 count=8
   sudo chmod 400 /etc/luks-keys/data.key

2. Add the key file to the device. Enter your existing passphrase when prompted:

   sudo cryptsetup luksAddKey /dev/vdb /etc/luks-keys/data.key

   The passphrase keeps working alongside the key file.

3. Find the UUID of the encrypted device:

   sudo blkid /dev/vdb

4. Add the following line to /etc/crypttab, replacing the UUID with your own:

   data UUID=354d8ba8-7c36-4fd0-a64c-8fc2e36818fb /etc/luks-keys/data.key luks

5. Add the following line to /etc/fstab. The nofail option lets the server finish booting even if the device can't be unlocked:

   /dev/mapper/data /mnt/data ext4 defaults,nofail 0 2

6. Restart the server and check that the device is mounted:

   sudo reboot

   lsblk /dev/vdb

6. Back up the LUKS header

The LUKS header at the start of the device holds the key slots that your passphrases and key files unlock. If the header is damaged, the data can't be decrypted even with the right passphrase. Keep a backup of it:

sudo cryptsetup luksHeaderBackup /dev/vdb --header-backup-file /root/data-luks-header.img

Copy the file to a safe place outside the server, then delete it from the server. For example, from your own computer:

scp root@<server-ip>:/root/data-luks-header.img .

To restore the header, copy the file back to the server and run:

sudo cryptsetup luksHeaderRestore /dev/vdb --header-backup-file /root/data-luks-header.img

A header backup opens the device with the passphrases and key files that were valid when you made it, even after you change or remove them on the device. Protect it like a passphrase, and make a new header backup whenever you change your passphrases or rotate the encryption key.

Manage passphrases and keys

A LUKS2 device has up to 32 key slots. Each passphrase or key file uses one slot. To list the slots in use:

sudo cryptsetup luksDump /dev/vdb

The slots are listed under Keyslots.

Add a passphrase, for example a recovery passphrase kept by another person. Enter an existing passphrase, then the new one:

sudo cryptsetup luksAddKey /dev/vdb

Change a passphrase. Enter the passphrase to change, then the new one:

sudo cryptsetup luksChangeKey /dev/vdb

Remove a passphrase. Enter the passphrase to remove:

sudo cryptsetup luksRemoveKey /dev/vdb

Make sure at least one other passphrase or key file still works before you remove one.

Rotate the encryption key

Passphrases and key files unlock the volume key, which encrypts the data. Changing a passphrase doesn't change the volume key. To replace the volume key, re-encrypt the device. This works while the device is mounted and in use.

Re-encrypting needs every key slot to be unlocked. If you use a key file, re-encrypt with one passphrase slot, which removes the other slots, and then add the key file again:

1. Find the number of a slot that a passphrase unlocks in the luksDump output, then re-encrypt the device with that slot. Enter its passphrase when prompted:

   sudo cryptsetup reencrypt /dev/vdb --key-slot 0

   Enter passphrase for key slot 0:
   Auto-detected active dm device 'data' for data device /dev/vdb.
   Finished, time 01m09s,    9 GiB written, speed 146.6 MiB/s

   Re-encryption rewrites the whole device, so the time it takes depends on the device size.

2. Add the key file again, and any other passphrases you use:

   sudo cryptsetup luksAddKey /dev/vdb /etc/luks-keys/data.key

The remaining passphrase can move to a different slot number during re-encryption. Check luksDump before you use slot numbers again.

After re-encrypting, make a new header backup. A header backup from before the re-encryption still accepts the old passphrases, but the data can no longer be decrypted with it.

Backups and clones

Backups and clones of the storage device contain the encrypted data and the LUKS header as it was when the backup or clone was made. To open a restored backup, use a passphrase or key file that was valid at that time. Changing or removing a passphrase on the device doesn't change it in existing backups.

A restored copy has the same UUID as the original device. If both are attached to the same server and you unlock automatically with a key file, the server can unlock and mount the copy at /mnt/data instead of the original when it starts. Attach the copy to a different server, or give it a new UUID before you restart the server again:

1. Check which device is mounted. In this example, the copy is vdc and it was mounted instead of the original:

   lsblk /dev/vdb /dev/vdc

   NAME   MAJ:MIN RM SIZE RO TYPE  MOUNTPOINTS
   vdb    253:16   0  10G  0 disk
   vdc    253:32   0  10G  0 disk
   └─data 252:0    0  10G  0 crypt /mnt/data

   If the copy is mounted, unmount and lock it:

   sudo umount /mnt/data
   sudo cryptsetup close data

2. Give the copy a new UUID. Type YES to confirm:

   sudo cryptsetup luksUUID --uuid "$(cat /proc/sys/kernel/random/uuid)" /dev/vdc

3. Restart the server. The original device is unlocked and mounted at /mnt/data again.

4. Open the copy with a different name for the unlocked device, and mount it somewhere else:

   sudo cryptsetup open /dev/vdc restored
   sudo mount /dev/mapper/restored /mnt

Destroy the encryption keys

To make the data permanently unreadable, erase all key slots from the device:

1. Unmount and lock the device:

   sudo umount /mnt/data
   sudo cryptsetup close data

2. Erase the key slots. Type YES to confirm:

   sudo cryptsetup erase /dev/vdb

   After this, no passphrase or key file opens the device:

   No usable keyslot is available.

3. Remove the device's lines from /etc/fstab and /etc/crypttab, and delete the key file if you used one.

Header backups, storage backups, and clones still contain key slots that open the data. Delete them as well, then delete the storage device in the Control Panel.