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). 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
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 targets" 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.
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)
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.
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. Note that while the cipher algorithm is always as the same as the algorithm used for data encryption, its key size depends on used hash algorithm.
In other words, while data encryption can use AES-128, the ESSIV calculation with SHA256 will use AES-256. ESSIV takes hash algorithm as an 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)
tcw: Compatible implementation of the key seeded IV with additional whitening (to CBC mode)
used by the TrueCrypt encryption system (prior to version 4.2). Available since: 1.13.0 (kernel 3.13)
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)
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)
same_cpu_crypt: Perform encryption using the same cpu that IO was submitted on.
The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs. Available since: 1.14.0 (kernel 4.0)
submit_from_crypt_cpus: Disable offloading writes to a separate thread after encryption.
There are some situations where offloading write bios from the encryption threads to a single thread degrades performance significantly.
The default is to offload write bios to the same thread because it benefits CFQ to have writes submitted using the same context. Available since: 1.14.0 (kernel 4.0)