====== Managing LUKS on Debian ======

LUKS (Linux Unified Key Setup) is the disk encryption software that's available on Debian. It sits between the file system and the block device, and encrypts all data as it passes through.

Since LUKS works directly on the block device, all commands listed below must be executed **as root**.

===== Installing cryptsetup =====

Cryptsetup is the command used to manage LUKS. You can install it like this:

<code>
apt-get install cryptsetup
</code>

===== Creating an encrypted volume =====

<code>
cryptsetup -v --type luks2 luksFormat /dev/DEVICE
</code>

You can also create an encrypted volume on a disk image instead. In that case, first create the disk image with a command like the following:

<code>
touch disk.img
fallocate -v -l 100MiB disk.img
</code>

Don't use sparse images. LUKS will consider them too small.
===== Opening an encrypted volume =====

<code>
cryptsetup luksOpen /dev/DEVICE volumename
</code>

The volume should then become available at /dev/mapper/volumename

===== Closing an encrypted volume =====

<code>
cryptsetup luksClose volumename
</code>


===== Listing slots =====

Each method that can unlock a disk is stored in a slot, in a header on the LUKS partition. You can list all slots (and other metadata) by issuing the following command:

<code bash>
cryptsetup luksDump /dev/sda3
</code>

This would list the slots for disk sda3.

===== Adding a password slot =====

You can add an additional password that can unlock the disk by executing:

<code bash>
cryptsetup luksAddKey /dev/sda3
</code>

This will add a new password for disk sda3. You will be prompted for an existing password!

===== Adding a keyfile slot =====

This method uses a file to unlock the disk. You can add it entirely the same as a new password, with just an additional parameter for the file:

<code bash>
cryptsetup luksAddKey /dev/sda3 /home/keyfile.txt
</code>

This will add a new keyfile (located in /home/keyfile.txt) for disk sda3. You will be prompted to authenticate with an existing method!

===== Adding a Yubikey slot =====

See [[public:unlocking_debian_luks_with_a_yubikey_at_boot|]].

===== Clearing a slot =====

If you want to remove an authentication method, you need to clear the corresponding slot. You can do so by issuing the following command:

<code bash>
cryptsetup -v luksKillSlot /dev/sda3 0
</code>

This would clear slot 0 (slots are zero-based) on disk sda3. Note that you will be asked to authenticate with an authentication method stored in another slot.

===== References =====

  * ''man cryptsetup''
  * https://askubuntu.com/questions/1319688/luks-how-can-i-add-more-password-slots-or-remove-change-a-password

{{tag>Debian LUKS}}