Device encryption ( Cryptsetup )

This section covers how to manually utilize dm-crypt from the command line to encrypt a system.

Describe the bug

Preparation

Before using cryptsetup, always make sure the dm_crypt kernel module is loaded.

Cryptsetup usage

Cryptsetup is the command line tool to interface with dm-crypt for creating, accessing and managing encrypted devices. The tool was later expanded to support different encryption types that rely on the Linux kernel device-mapper and the cryptographic modules. The most notable expansion was for the Linux Unified Key Setup (LUKS) extension, which stores all of the needed setup information for dm-crypt on the disk itself and abstracts partition and key management in an attempt to improve ease of use. Devices accessed via the device-mapper are called blockdevices. For further information see Disk encryption#Block device encryption.

The tool is used as follows:

# cryptsetup <OPTIONS> <action> <action-specific-options> <device> <dmname>

It has compiled-in defaults for the options and the encryption mode, which will be used if no others are specified on the command line. Have a look at

$ cryptsetup --help 

which lists options, actions and the default parameters for the encryption modes in that order. A full list of options can be found on the man page. Since different parameters are required or optional, depending on encryption mode and action, the following sections point out differences further. Blockdevice encryption is fast, but speed matters a lot too. Since changing an encryption cipher of a blockdevice after setup is difficult, it is important to check dm-crypt performance for the individual parameters in advance:

$ cryptsetup benchmark 

can give guidance on deciding for an algorithm and key-size prior to installation. If certain AES ciphers excel with a considerable higher throughput, these are probably the ones with hardware support in the CPU.

Cryptsetup passphrases and keys

An encrypted blockdevice is protected by a key. A key is either:

• a passphrase: see Security#Passwords.
• a keyfile, see #Keyfiles.

Both key types have default maximum sizes: passphrases can be up to 512 characters and keyfiles up to 8192kiB.

An important distinction of LUKS to note at this point is that the key is used to unlock the master-key of a LUKS-encrypted device and can be changed with root access. Other encryption modes do not support changing the key after setup, because they do not employ a master-key for the encryption. See Disk encryption#Block device encryption for details.

Encryption options with dm-crypt

Cryptsetup supports different encryption operating modes to use with dm-crypt:

• --type luks for using the default LUKS format version (LUKS1 with cryptsetup < 2.1.0, LUKS2 with cryptsetup ≥ 2.1.0),
• --type luks1 for using LUKS1, the most common version of LUKS,
• --type luks2 for using LUKS2, the latest available version of LUKS that allows additional extensions,
• --type plain for using dm-crypt plain mode,
• --type loopaes for a loopaes legacy mode,
• --type tcrypt for a TrueCrypt compatibility mode.

The basic cryptographic options for encryption cipher and hashes available can be used for all modes and rely on the kernel cryptographic backend features. All that are loaded and available to use as options at runtime can be viewed with:

$ less /proc/crypto 

The following introduces encryption options for the luks, luks1, luks2 and plain modes. Note that the tables list options used in the respective examples in this article and not all available ones.

Encryption options for LUKS mode

The cryptsetup action to set up a new dm-crypt device in LUKS encryption mode is luksFormat. Unlike the name implies, it does not format the device, but sets up the LUKS device header and encrypts the master-key with the desired cryptographic options.

As LUKS is the default encryption mode, all that is needed to create a new LUKS device with default parameters (-v is optional):

# cryptsetup -v luksFormat device

For comparison, one can specify the default options manually too:

# cryptsetup -v --type luks --cipher aes-xts-plain64 --key-size 256 --hash sha256 --iter-time 2000 --use-urandom --verify-passphrase luksFormat device

Defaults are compared with a cryptographically higher specification example in the table below, with accompanying comments:

The properties of LUKS features and options are described in the LUKS1 (pdf) and LUKS2 (pdf) specifications.

Encrypting devices with cryptsetup

This section shows how to employ the options for creating new encrypted blockdevices and accessing them manually.

Encrypting devices with LUKS mode

Formatting LUKS partitions

In order to setup a partition as an encrypted LUKS partition execute:

# cryptsetup luksFormat --type luks2 device

You will then be prompted to enter a password and verify it.

See #Encryption options for LUKS mode for command line options.

You can check the results with:

# cryptsetup luksDump device

You will note that the dump not only shows the cipher header information, but also the key-slots in use for the LUKS partition.

The following example will create an encrypted root partition on /dev/sda1 using the default AES cipher in XTS mode with an effective 256-bit encryption

# cryptsetup -s 512 luksFormat --type luks2 /dev/sda1

Using LUKS to format partitions with a keyfile

When creating a new LUKS encrypted partition, a keyfile may be associated with the partition on its creation using:

# cryptsetup luksFormat --type luks2 device /path/to/mykeyfile

See #Keyfiles for instructions on how to generate and manage keyfiles.

Unlocking/Mapping LUKS partitions with the device mapper

Once the LUKS partitions have been created, they can then be unlocked.

The unlocking process will map the partitions to a new device name using the device mapper. This alerts the kernel that device is actually an encrypted device and should be addressed through LUKS using the /dev/mapper/dm_name so as not to overwrite the encrypted data. To guard against accidental overwriting, read about the possibilities to backup the cryptheader after finishing setup.

In order to open an encrypted LUKS partition execute:

# cryptsetup open device dm_name

You will then be prompted for the password to unlock the partition. Usually the device mapped name is descriptive of the function of the partition that is mapped. For example the following unlocks a luks partition /dev/sda1 and maps it to device mapper named cryptroot:

# cryptsetup open /dev/sda1 cryptroot 

Once opened, the root partition device address would be /dev/mapper/cryptroot instead of the partition (e.g. /dev/sda1).

For setting up LVM ontop the encryption layer the device file for the decrypted volume group would be anything like /dev/mapper/cryptroot instead of /dev/sda1. LVM will then give additional names to all logical volumes created, e.g. /dev/lvmpool/root and /dev/lvmpool/swap.

In order to write encrypted data into the partition it must be accessed through the device mapped name. The first step of access will typically be to create a filesystem. For example:

# mkfs -t ext4 /dev/mapper/cryptroot

The device /dev/mapper/cryptroot can then be mounted like any other partition.

To close the luks container, unmount the partition and do:

# cryptsetup close cryptroot

Encrypting devices with plain mode

The creation and subsequent access of a dm-crypt plain mode encryption both require not more than using the cryptsetup open action with correct parameters. The following shows that with two examples of non-root devices, but adds a quirk by stacking both (i.e. the second is created inside the first). Obviously, stacking the encryption doubles overhead. The usecase here is simply to illustrate another example of the cipher option usage.

A first mapper is created with cryptsetup’s plain-mode defaults, as described in the table’s left column above

# cryptsetup --type plain -v open /dev/sdaX plain1

Enter passphrase: 
Command successful.

Now we add the second blockdevice inside it, using different encryption parameters and with an (optional) offset, create a filesystem and mount it

# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10  open /dev/mapper/plain1 plain2

Enter passphrase:

# lsblk -p

 NAME                                                     
 /dev/sda                                     
 ├─/dev/sdaX          
 │ └─/dev/mapper/plain1     
 │   └─/dev/mapper/plain2              
 ...

# mkfs -t ext2 /dev/mapper/plain2
# mount -t ext2 /dev/mapper/plain2 /mnt
# echo "This is stacked. one passphrase per foot to shoot." > /mnt/stacked.txt

We close the stack to check access works

# cryptsetup close plain2
# cryptsetup close plain1

First, let us try to open the filesystem directly:

# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/sdaX plain2

# mount -t ext2 /dev/mapper/plain2 /mnt

mount: wrong fs type, bad option, bad superblock on /dev/mapper/plain2,
      missing codepage or helper program, or other error

Why that did not work? Because the “plain2” starting block (10) is still encrypted with the cipher from “plain1”. It can only be accessed via the stacked mapper. The error is arbitrary though, trying a wrong passphrase or wrong options will yield the same. For dm-cryptplain mode, the open action will not error out itself.

Trying again in correct order:

# cryptsetup close plain2    # dysfunctional mapper from previous try

# cryptsetup --type plain open /dev/sdaX plain1

Enter passphrase:

# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/mapper/plain1 plain2

Enter passphrase:

# mount /dev/mapper/plain2 /mnt && cat /mnt/stacked.txt

This is stacked. one passphrase per foot to shoot.

dm-crypt will handle stacked encryption with some mixed modes too. For example LUKS mode could be stacked on the “plain1” mapper. Its header would then be encrypted inside “plain1” when that is closed.

Available for plain mode only is the option --shared. With it a single device can be segmented into different non-overlapping mappers. We do that in the next example, using a loopaes compatible cipher mode for “plain2” this time:

# cryptsetup --type plain --offset 0 --size 1000 open /dev/sdaX plain1

Enter passphrase:

# cryptsetup --type plain --offset 1000 --size 1000 --shared --cipher=aes-cbc-lmk --hash=sha256 open /dev/sdaX plain2

Enter passphrase:

# lsblk -p

NAME                    
dev/sdaX                    
├─/dev/sdaX               
│ ├─/dev/mapper/plain1     
│ └─/dev/mapper/plain2     
...

As the devicetree shows both reside on the same level, i.e. are not stacked and “plain2” can be opened individually.

Cryptsetup actions specific for LUKS

Key management

It is possible to define up to 8 different keys per LUKS partition. This enables the user to create access keys for save backup storage: In a so-called key escrow, one key is used for daily usage, another kept in escrow to gain access to the partition in case the daily passphrase is forgotten or a keyfile is lost/damaged. Also a different key-slot could be used to grant access to a partition to a user by issuing a second key and later revoking it again.

Once an encrypted partition has been created, the initial keyslot 0 is created (if no other was specified manually). Additional keyslots are numbered from 1 to 7. Which keyslots are used can be seen by issuing

# cryptsetup luksDump /dev/<device> | grep BLED

Key Slot 0: ENABLED
Key Slot 1: ENABLED
Key Slot 2: ENABLED
Key Slot 3: DISABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

Where <device> is the volume containing the LUKS header. This and all the following commands in this section work on header backup files as well.

Adding LUKS keys

Adding new keyslots is accomplished using cryptsetup with the luksAddKey action. For safety it will always, i.e. also for already unlocked devices, ask for a valid existing key (“any passphrase”) before a new one may be entered:

# cryptsetup luksAddKey /dev/<device> (/path/to/<additionalkeyfile>)

Enter any passphrase:
Enter new passphrase for key slot:
Verify passphrase: 

If /path/to/<additionalkeyfile> is given, cryptsetup will add a new keyslot for <additionalkeyfile>. Otherwise a new passphrase will be prompted for twice. For using an existing keyfile to authorize the action, the --key-file or -d option followed by the “old” <keyfile> will try to unlock all available keyfile keyslots:

# cryptsetup luksAddKey /dev/<device> (/path/to/<additionalkeyfile>) -d /path/to/<keyfile>

If it is intended to use multiple keys and change or revoke them, the --key-slot or -S option may be used to specify the slot:

# cryptsetup luksAddKey /dev/<device> -S 6

Enter any passphrase: 
Enter new passphrase for key slot: 
Verify passphrase:

# cryptsetup luksDump /dev/sda8 | grep 'Slot 6'

Key Slot 6: ENABLED

To show an associated action in this example, we decide to change the key right away:

# cryptsetup luksChangeKey /dev/<device> -S 6

Enter LUKS passphrase to be changed: 
Enter new LUKS passphrase:

before continuing to remove it.

Removing LUKS keys

There are three different actions to remove keys from the header:

• luksRemoveKey is used to remove a key by specifying its passphrase/key-file.
• luksKillSlot may be used to remove a key from a specific key slot (using another key). Obviously, this is extremely useful if you have forgotten a passphrase, lost a key-file, or have no access to it.
• luksErase is used to quickly remove all active keys.

For above warning it is good to know the key we want to keep is valid. An easy check is to unlock the device with the -v option, which will specify which slot it occupies:

# cryptsetup -v open /dev/<device> testcrypt

Enter passphrase for /dev/<device>: 
Key slot 1 unlocked.
Command successful.

Now we can remove the key added in the previous subsection using its passphrase:

# cryptsetup luksRemoveKey /dev/<device>

Enter LUKS passphrase to be deleted:

If we had used the same passphrase for two keyslots, the first slot would be wiped now. Only executing it again would remove the second one.

Alternatively, we can specify the key slot:

# cryptsetup luksKillSlot /dev/<device> 6

Enter any remaining LUKS passphrase:

Note that in both cases, no confirmation was required.

# cryptsetup luksDump /dev/sda8 | grep 'Slot 6'

Key Slot 6: DISABLED

To re-iterate the warning above: If the same passphrase had been used for key slots 1 and 6, both would be gone now.