Dm-crypt

dm-crypt is a disk encryption system using the kernels crypto API framework and device mapper subsystem. With dm-crypt, administrators can encrypt entire disks, logical volumes, partitions, but also single files.

The dm-crypt subsystem supports the Linux Unified Key Setup (LUKS) structure, which allows for multiple keys to access the encrypted data, as well as manipulate the keys (such as changing the keys, adding additional passphrases, etc.) Although dm-crypt supports non-LUKS setups as well, this article will focus on the LUKS functionality mostly due to its flexibility, manageability as well as broad support in the community.

Configuration
There are two prerequisites before one can start using dm-crypt:


 * 1) Configuration of the Linux kernel
 * 2) Installation of the  package

Kernel Configuration
To use dm-crypt there are a number of configuration entries that are necessary.

First of all, support for the device mapper infrastructure as well as the crypt target must be included:

Next, the Linux kernel needs to support the set of cryptographic APIs that the administrator wants to use for encryption. These can be found under the Cryptographic API section:

If the root file system will be encrypted as well, then an initial ram file system needs to be created in which the root filesystem is decrypted before it is mounted. Thus this requires initramfs support as well:

Cryptsetup installation
The package provides the  command, which is used to open or close the encrypted storage as well as manage the passphrases or keys associated with it.

Keyfile or passphrase
In order to start with encrypted storage, the administrator will need to decide which method to use for the encryption key. With the choice is either a passphrase or a keyfile. In case of a keyfile, this can be any file, but it is recommended to use a file with random data which is properly protected (considering that access to this keyfile will mean access to the encrypted data).

To create a keyfile, one can use the command:

In the next sections, we will show every command for both situations - passphrase and keyfile. Of course, only one method is necessary.

Creating an encrypted storage platform
In order to create an encrypted storage platform (which can be a disk, partition, file, ...) use the command with the   action.

For instance, to have as the storage medium for the encrypted data:

To use a keyfile instead of a passphrase:

The  tells  which keylength to use for the real encryption key (unlike the passphrase or keyfile, which are used to access this real encryption key).

Opening the encrypted storage
In order to open up the encrypted storage (i.e. make the real data accessible through transparent decryption), use the  action.

If a keyfile is used, then the command would look like so:

When the command finishes successfully, then a new device file called will be made available.

If this is the first time this encrypted device is used, it needs to be formatted. The following example uses the Btrfs file system but of course any other file system will do:

Once the file system is formatted, or the formatting was already done in the past, then the device file can be mounted on the system:

Closing the encrypted storage
In order to close the encrypted storage (i.e. ensure that the real data is no longer accessible through transparent decryption), use the  action:

Of course, make sure that the device is no longer in use.

Manipulating LUKS keys
LUKS keys are used to access the real encryption key. They are stored in slots in the header of the (encrypted) partition, disk or file.

Listing the slots
With the  action, information about the encrypted partition, disk or file can be shown. This includes the slots:

In the above example, two slots are used. Note that  does not give away anything sensitive - it is merely displaying the LUKS header content. No decryption key has to be provided in order to call.

Adding a keyfile or passphrase
In order to add an additional keyfile or passphrase to access the encrypted storage, use the  action:

To use a keyfile to unlock the key (but still add in a passphrase):

If a keyfile is to be added (say ):

Or, to use the first keyfile to unlock the main key:

Removing a keyfile or passphrase
With the  action, a keyfile or passphrase can be removed (so they can no longer be used to decrypt the storage):

Or to remove a keyfile:

Make sure that at least one method for accessing the data is still available. Once a passphrase or keyfile is removed for use, this cannot be recovered again.

Emptying a slot
Suppose the passphrase or keyfile is no longer known, then the slot can be freed. Of course, this does require prior knowledge of which slot that the passphrase or keyfile was stored in.

For instance, to empty out slot 2 (which is the third slot as slots are numbered starting from 0):

This command will ask for a valid passphrase before continuing. Or one can pass on the keyfile to use:

Boot setup of additional disks
It is possible to have a secondary encrypted disk mounted during boot.

To make this happen, it is necessary to configure dm-crypt, configure fstab, and make dmcrypt start during boot.

Configure dm-crypt
Edit /etc/conf.d/dmcrypt adding an entry specifying:
 * source - the device to decrypt
 * key - the keyfile used to unlock the device. This can be located on an encrypted root disk, as that will already be decrypted when dm-crypt starts
 * target - the name to give the decrypted device (will be created in /dev/mapper/):

Configure fstab
Identified the UUID of the decrypted device using the blkid command:

Edit /etc/fstab adding the entry to mount as you normally would, using the UUID which was just found:

Add initscript to bootlevel
Finally execute the following command to have dm-crypt startup during the boot phase:

Additional resources

 * Dm-crypt full disk encryption on the Gentoo Wiki provides supplementary information on using encrypted file systems for Gentoo Linux installations
 * The cryptsetup FAQ hosted on GitLab covers a wide range of frequently asked questions.