dm-crypt: Linux kernel device-mapper crypto target
Device-mapper is infrastructure in the Linux 2.6 and 3.x 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).
Mapping table in device mapper is defined like
<start_sector> <size> <target name> <target mapping table>
Sectors are always 512B sectors (even if device has bigger hw sector like 4k).
Table fields are separated by space.
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.
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>]
Examples of full cipher/mode/iv specifications:
aes-cbc-essiv:sha256 aes-xts-plain64 aes:64-cbc-lmk twofish-ecb serpent-cbc-plain
Example of optional parameters section:
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
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.
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.
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>
The DMCrypt page is written and maintained by Milan Broz (with help of other project users and developers).