GUIDE · PREVIEW
EDIT ON GITHUB →
GUIDE / CON.17
source: docs/guide/concepts/dm-crypt.md
Concepts

dm-crypt

What It Is

dm-crypt is the Linux kernel's disk encryption subsystem. It uses the device-mapper framework to create a virtual block device that transparently encrypts everything written to it and decrypts everything read from it. The actual disk stores only ciphertext.

dm-crypt is the engine; LUKS is the key management layer on top. Most users interact with LUKS (via cryptsetup), which sets up dm-crypt internally. But dm-crypt can also be used directly for simpler use cases.

Why It Matters

dm-crypt provides full-disk encryption at the block level. This means:

  • Every byte written to disk is encrypted, including filesystem metadata
  • The filesystem (ext4, XFS, etc.) doesn't know encryption exists
  • Any filesystem can be used on top of dm-crypt
  • Encryption is transparent to applications

How It Works

Device Mapper

dm-crypt is a device-mapper target. Device-mapper is a Linux kernel framework that creates virtual block devices by mapping I/O requests to underlying physical devices. Other device-mapper targets include:

  • dm-linear: Simple concatenation of devices
  • dm-striped: RAID-0 striping
  • dm-mirror: RAID-1 mirroring
  • dm-thin: Thin provisioning
  • dm-crypt: Encryption

When you open a LUKS partition, cryptsetup tells the kernel to create a dm-crypt mapping:

/dev/vdb (physical, encrypted) --> dm-crypt --> /dev/mapper/persist (virtual, plaintext)

Applications read/write /dev/mapper/persist. dm-crypt transparently handles the encryption/decryption using the master key.

Ciphers and Modes

The default for LUKS2 is AES-256-XTS (also called aes-xts-plain64):

  • AES-256: The encryption algorithm (256-bit key)
  • XTS: The block cipher mode (designed for disk encryption -- handles sector-level encryption without leaking patterns)
  • plain64: The IV (initialization vector) generation method (sector number as 64-bit integer)

XTS uses two AES keys (the 256-bit master key is split into two 128-bit keys), one for encryption and one for "tweaking" (making each sector's encryption unique). This prevents an attacker from learning whether two sectors contain the same plaintext.

Performance

Modern CPUs have hardware AES acceleration (AES-NI on Intel/AMD). With AES-NI, dm-crypt adds minimal overhead -- typically under 5% for sequential I/O and negligible for random I/O. Without AES-NI (very old hardware), encryption can reduce throughput significantly.

How FortrOS Uses It

LUKS on /persist: The primary use. dm-crypt encrypts the entire /persist partition. Managed via LUKS2 keyslots.

Per-service scratch encryption: FortrOS uses dm-crypt directly (without LUKS) for per-service scratch volumes. Each service gets its own encrypted sparse file:

  1. Create a sparse file (fallocate)
  2. Set up a loop device (losetup)
  3. Format with LUKS2 (cryptsetup luksFormat)
  4. Open (cryptsetup luksOpen)
  5. Create filesystem (mkfs.ext4)
  6. Mount

The key comes from the key service (HKDF-derived per-service key). The reconciler handles setup and teardown -- the app doesn't know or care that its data directory is an encrypted volume.

Scratch volumes have two data classes, declared in the workload manifest:

  • Ephemeral (default): Destroyed on reboot. Key is random per boot. Good for stateless services, build caches, temp files. No recovery possible or needed.
  • Persistent: LUKS keyslot survives reboot. The key is derived from the key service (deterministic, same key on every boot). After reboot, the reconciler reopens the volume and the app resumes with its data intact. Good for databases, build caches worth keeping, and any service where cold start is expensive. Another instance of the same app on a different node can also open the volume if the key service provides the same derived key (the key is per-service, not per-node).

Swap encryption: All swap devices are encrypted with a random key generated per boot. The key is discarded on shutdown -- swap contents are unrecoverable after power loss.

Alternatives

fscrypt (file-based encryption): Encrypts individual directories within a filesystem. More granular than dm-crypt but doesn't encrypt filesystem metadata. Used by Android (FBE) and supported on ext4/F2FS.

eCryptfs: An older file-level encryption filesystem that layers on top of existing filesystems. Largely superseded by fscrypt.

Software RAID + encryption: Encrypt individual disks then RAID them (encryption below RAID) or RAID then encrypt (encryption above RAID). FortrOS doesn't use RAID -- storage replication is handled by the org's shard system.

Links