dm-crypt: Linux kernel device-mapper crypto target

About dm-crypt

Device-mapper is infrastructure in the Linux 2.6 kernel that provides a generic way to create virtual layers of block devices.

Device-mapper crypt target provides transparent encryption of block devices using the kernel crypto API.

The user can basically specify one of the symmetric ciphers, an encryption mode, a key (of any allowed size), an iv generation mode and then the user can create a new block device in /dev.

Writes to this device will be encrypted and reads decrypted. You can mount your filesystem on it as usual or stack dm-crypt device with another device like RAID or LVM volume.

Basic documentation of dm-crypt mapping table comes with kernel source and the latest version is available in git repository.

To enable dm-crypt support, enable CONFIG_DM_CRYPT in Device Drivers/Multi-device support (RAID and LVM) configuration option. Most of distributions have dm-crypt included by default.

To configure you need userspace components: device mapper library (part of LVM2 package) and cryptsetup. All these packages are usually included in your distro repository already.

Check /proc/crypto which contains supported ciphers and modes (but note it contains only currently loaded crypto API modules).
There is currently no better way how to list all available variations of cipher and modes if the crypto modules are not loaded.

Device mapper crypt table mapping line specification

Mapping table in device mapper is defined like

<start_sector> <size> <target name> <target mapping table>

• start_sector is 0 (for tables using only one mapped segment, iow table contains only one line)
• size is size of device in sectors
• target name is name of mapping target, here "crypt" for dm-crypt

Sectors are always 512B sectors (even if device has bigger hw sector like 4k).

Table fields are separated by space.

dm-crypt target version

Every device-mapper target has internal version which is increased when some new feature is added. (With exceptions caused by developer's forgetfulness. ;-)

To check which version you have installed, load the dm target module (dm-crypt.ko for dm-crypt) and use "dmsetup target" to check version.

Note that crypt version target is not necessarily related to exact Linux kernel version, some distributions backport changes, so to check if some feature is implemented you need always check dm-crypt target version.

Mapping table for crypt target

The basic syntax is common for all 1.x.y dm-crypt target versions. If some extension was added later, it is mentioned in the description.

<cipher[:keycount]-chainmode-ivmode[:ivopts]> <key> <iv_offset> <device path> <offset> [<#opt_params> <opt_params>]

• cipher: Encryption block cipher.
  Example: aes, twofish, serpent.

• keycount: Multi-key compatibility mode.
  You can define keycount keys and then sectors are encrypted according to their offsets
  (sector 0 uses key0, sector 1 uses key1 etc). keycount must be a power of two.
  This parameter is used for loop-AES compatibility mode.
  Available since: 1.10.0 (kernel 2.6.38)

• chainmode: Block cipher encryption mode.
  Example: cbc, xts.

• ivmode: Initialization Vector (IV) used for selected block mode (if block mode requires IV).
  Unless block ciphers and encryption modes, IV generators are implemented directly inside dm-crypt module.

IV generators

• plain: the initial vector is the 32-bit little-endian version of the sector number, padded with zeros if necessary.

• plain64: the initial vector is the 64-bit little-endian version of the sector number, padded with zeros if necessary.
  Available since: 1.7.0 (no proper version set) (kernel 2.6.33)

• essiv: "encrypted sector|salt initial vector", the sector number is encrypted with the bulk cipher using a salt as key.
  The salt is derived from the bulk cipher's key via hashing.
  ESSIV takes hash algorithm as option, so the format is essiv:hash, e.g. essiv:sha256.
  Available since: 1.1.0 (kernel 2.6.10)

• benbi: the 64-bit "big-endian 'narrow block'-count", starting at 1
  Available since: 1.3.0 (no proper version set) (kernel 2.6.20)

• null: the initial vector is always zero. Provides compatibility with obsolete loop_fish2 devices.
  Available since: 1.5.0 (kernel 2.6.22)

• lmk: Compatible implementation of the block chaining mode used by the Loop-AES block device encryption system.
  Available since: 1.10.0 (kernel 2.6.38)

Examples of full cipher/mode/iv specifications:

aes-cbc-essiv:sha256
aes-xts-plain64
aes:64-cbc-lmk
twofish-ecb
serpent-cbc-plain

• key: Key used for encryption. It is encoded as a hexadecimal number (one character represents 4 bits).
  You can only use key sizes that are valid for the selected cipher.
  For multikey mode are all keys of the same length concatenated to one string.

• iv_offset: The IV offset is a sector count that is added to the sector number before creating the IV.
  It can be used to create a map that starts after the first encrypted sector.
  Usually you'll set it to zero except your device is only partially available or you need to configure some mode compatible with other encryption system.

• device path: This is the device that is going to be used as backend and contains the encrypted data.
  You can specify it as a path like /dev/xxx or a device number major:minor.

• offset: Starting sector within the device where the encrypted data begins.

• #opt_params: Number of optional parameters. If there are no optional parameters, the optional parameters section can be skipped or it can be zero. Otherwise it is the number of following arguments.
  Available since: 1.11.0 (kernel 3.1)

Optional parameters

• allow_discards: Allow block discard requests (a.k.a. TRIM) for the crypt device.
  The default is to ignore discard requests.
  Assess the specific security risks carefully before enabling this option. For example, allowing discards on encrypted devices
  may lead to the leak of information about the ciphertext device (filesystem type, used space etc.) if the discarded blocks
  can be located easily on the device later.
  Available since: 1.11.0 (kernel 3.1)

Example of optional parameters section:

1 allow_discards

Example of full mapping table

0 417792 crypt aes-xts-plain64 e8cfa3dbfe373b536be43c5637387786c01be00ba5f730aacb039e86f3eb72f3 0 8:16 0
|    |     |    |   |     |                                 |                                   |  |   | 
start|     |    |  mode   IV                                |                                   |  |   offset
     size  |  cipher                                        |                                   |  device
         target                                        256bit-key                          IV offset


0 417792 crypt serpent-cbc-essiv:sha256 a7f67ad520bd83b9725df6ebd76c3eee 0 /dev/sdb 0
|    |     |      |     |     |     |                |                   |     |    | 
start|     |      |    mode   IV  IV-opts            |                   |     |   offset
     size  |    cipher                               |                   |  device
         target                                 128bit-key          IV offset


Optional section example:

0 417792 crypt serpent-cbc-essiv:sha256 a7f67ad520bd83b9725df6ebd76c3eee 0 /dev/sdb 0 1 allow_discards
                                                                                      |        | 
                                                                                      |   optional parameter
                                                                                    count

Configuration with dmsetup tool

Dmsetup is used to create and remove devices, get information about devices or reload tables (that means changing the mapping while the device is in use).

Usually this tool is only used for low-level access to dm device, example here is mentioned just to show how the low level parameters works. Always prefer using cryptsetup if possible.

To create device and specify mapping table, use dmsetup create <name> --table " ..." command.

The second example above is then created using

dmsetup create x --table "0 $(blockdev --getsz /dev/sdb) crypt serpent-cbc-essiv:sha256 a7f67ad...ee 0 /dev/sdb 0"

You can check the full mapping table using dmsetup table with optional --showkeys parameter.

Note that for all device-mapper operations is required root privilege (CAP_SYSADMIN).

The newly created device then appears as /dev/mapper/name.

Configuration using cryptsetup

cryptsetup utility support several modes. Plain mode is just equivalent of direct configuration of dmcrypt target with passphrase hashing but without on-disk metadata.

LUKS (Linux Unified Key Setup) is now the preferred way to set up disk encryption with dm-crypt using the cryptsetup utility, see cryptsetup project page.

Example of using cryptsetup

If you have keyfile (in binary format) in file /key, you can setup mapping in example above as

cryptsetup -d /key -s 128 -c serpent-cbc-essiv:sha256 create <name> /dev/sdb

If you want to use LUKS on-disk metadata with default cipher, use

cryptsetup luksFormat <device>
cryptsetup luksOpen <device> <name>