cryptsetup LUKS Encryption

cryptsetup cheatsheet — create, open, and manage LUKS encrypted volumes. cryptsetup luksFormat, luksOpen, luksClose, luksDump. Full disk encryption on Linux.

10 min read

What it is

cryptsetup is a command-line utility for setting up and managing encrypted disk devices using the Linux Unified Key Setup (LUKS) standard. You reach for it when you need to encrypt partitions, entire disks, or other block devices for data security.

Installation

Linux

cryptsetup is usually pre-installed on most Linux distributions. If not:

Debian/Ubuntu:

sudo apt update
sudo apt install cryptsetup

Fedora/CentOS/RHEL:

sudo dnf install cryptsetup
# or
sudo yum install cryptsetup

Arch Linux:

sudo pacman -S cryptsetup

macOS

cryptsetup is not natively available on macOS. For disk encryption on macOS, use the built-in FileVault.

Windows

cryptsetup is not natively available on Windows. For disk encryption on Windows, use the built-in BitLocker.

Core Concepts

  • LUKS (Linux Unified Key Setup): The standard for disk encryption on Linux. It provides a secure way to manage encryption keys and metadata on the encrypted device itself.
  • Cipher: The encryption algorithm used (e.g., AES-XTS, AES-CBC).
  • Key Size: The length of the encryption key in bits (e.g., 256 bits for AES).
  • Hash: The algorithm used for generating keys from passphrases (e.g., SHA256, SHA512).
  • Key Slots: LUKS supports multiple key slots, allowing several passphrases or key files to unlock the same encrypted device. This is useful for recovery or sharing access.
  • Plaintext Device: The underlying unencrypted block device (e.g., /dev/sda1, /dev/nvme0n1p3).
  • Ciphertext Device: The encrypted device mapped by cryptsetup (e.g., /dev/mapper/my_encrypted_volume).

Commands / Usage

Setting Up Encryption (Formatting a Device)

To encrypt a device, you need to format it with LUKS. This will erase all existing data on the device.

Create a new LUKS encrypted volume on a partition:

sudo cryptsetup luksFormat /dev/sdXN
  • Example: sudo cryptsetup luksFormat /dev/sdb1
  • Explanation: Initializes /dev/sdb1 with a LUKS header and prompts you to enter and confirm a strong passphrase.

Create a new LUKS encrypted volume on a whole disk (use with caution, ensure no important data exists):

sudo cryptsetup luksFormat /dev/sdX
  • Example: sudo cryptsetup luksFormat /dev/sdc
  • Explanation: Initializes the entire disk /dev/sdc with a LUKS header.

Create a LUKS volume with a specific cipher and key size:

sudo cryptsetup luksFormat --cipher aes-xts-plain64 --key-size 512 --hash sha512 /dev/sdXN
  • Example: sudo cryptsetup luksFormat --cipher aes-xts-plain64 --key-size 512 --hash sha512 /dev/sdd1
  • Explanation: Formats /dev/sdd1 using AES-XTS with a 512-bit key and SHA512 for key derivation. aes-xts-plain64 is a common and robust choice.

Opening (Unlocking) Encrypted Volumes

Once a LUKS volume is formatted, you need to "open" it to access the decrypted data. This maps the encrypted device to a new device in /dev/mapper/.

Open a LUKS volume with a passphrase:

sudo cryptsetup open /dev/sdXN <mapper_name>
  • Example: sudo cryptsetup open /dev/sdb1 my_secret_data
  • Explanation: Prompts for the passphrase for /dev/sdb1 and creates a decrypted device at /dev/mapper/my_secret_data.

Open a LUKS volume using a key file: First, create a key file (e.g., with dd if=/dev/urandom of=/path/to/keyfile bs=512 count=1). Then, add it to a LUKS key slot (see "Managing Keys" below).

sudo cryptsetup open --key-file /path/to/keyfile /dev/sdXN <mapper_name>
  • Example: sudo cryptsetup open --key-file /etc/cryptsetup-keys/mykey.bin /dev/sdc1 encrypted_drive
  • Explanation: Opens /dev/sdc1 using the key stored in /etc/cryptsetup-keys/mykey.bin and maps it to /dev/mapper/encrypted_drive.

Open a LUKS volume from a specific key slot (if multiple passphrases/keys exist):

sudo cryptsetup open --key-slot 1 /dev/sdXN <mapper_name>
  • Example: sudo cryptsetup open --key-slot 1 /dev/sde1 project_files
  • Explanation: Opens /dev/sde1 using the key stored in key slot 1 and maps it to /dev/mapper/project_files.

Closing (Locking) Encrypted Volumes

When you’re finished with an encrypted volume, you should close it to lock the data.

Close a mapped LUKS volume:

sudo cryptsetup close <mapper_name>
  • Example: sudo cryptsetup close my_secret_data
  • Explanation: Unmaps and locks the device /dev/mapper/my_secret_data.

Close a mapped LUKS volume by specifying the underlying device:

sudo cryptsetup close /dev/sdXN
  • Example: sudo cryptsetup close /dev/sdb1
  • Explanation: Closes any mapped device associated with the underlying LUKS device /dev/sdb1.

Managing Keys (Passphrases and Key Files)

LUKS supports multiple passphrases and key files for a single encrypted volume.

Add a new passphrase to an existing LUKS volume:

sudo cryptsetup luksAddKey /dev/sdXN
  • Example: sudo cryptsetup luksAddKey /dev/sdb1
  • Explanation: Prompts for the current passphrase (or another valid key) and then prompts for a new passphrase to add to an available key slot.

Add a key file to an existing LUKS volume:

sudo cryptsetup luksAddKey --key-file /path/to/newkeyfile /dev/sdXN
  • Example: sudo cryptsetup luksAddKey --key-file /root/recovery.key /dev/sdc1
  • Explanation: Adds the key from /root/recovery.key to /dev/sdc1. You’ll be prompted for a valid passphrase to authorize this.

Remove a passphrase or key file from a LUKS volume:

sudo cryptsetup luksRemoveKey /dev/sdXN <key_slot_identifier>
  • Example: sudo cryptsetup luksRemoveKey /dev/sdb1 0
  • Explanation: Removes the key associated with key slot 0 from /dev/sdb1. You’ll need to provide a valid passphrase to authorize the removal. You can also specify a passphrase directly if you know it, but this is less secure.

View LUKS header information and key slots:

sudo cryptsetup luksDump /dev/sdXN
  • Example: sudo cryptsetup luksDump /dev/sdb1
  • Explanation: Displays details about the LUKS header, including the cipher, key size, hash, and which key slots are in use.

Resizing Encrypted Volumes

Resizing LUKS volumes requires careful steps to ensure data integrity. It typically involves resizing the underlying partition first, then the LUKS container, and finally the filesystem within.

Resize the LUKS container (after resizing the underlying partition):

sudo cryptsetup resize /dev/sdXN
  • Example: sudo cryptsetup resize /dev/sdb1
  • Explanation: Resizes the LUKS container on /dev/sdb1 to match the new size of the underlying partition. This should be done after resizing the partition using tools like fdisk, parted, or gparted.

Recovery and Repair

Re-encrypting a volume (destructive, requires a valid key):

sudo cryptsetup luksReEncrypt /dev/sdXN
  • Example: sudo cryptsetup luksReEncrypt /dev/sdb1
  • Explanation: Allows you to change the LUKS cipher, key size, or hash without losing data, provided you can unlock the volume. You will be prompted for the current passphrase and then the new settings.

Repairing a LUKS header (advanced, use with extreme caution): This is a complex process and often involves having a backup of the original header. cryptsetup has limited direct repair capabilities. If the header is corrupted, recovery usually involves:

  1. Creating a new LUKS container with the same cipher and key size on a different device.
  2. Using dd to copy the original LUKS header (if recoverable from a backup or raw sector read) to the new container.
  3. Adding a passphrase to the new container.
  4. Attempting to unlock and access data.

This is highly data-dependent and risky. Always back up data before attempting header repair.

Other Useful Options

List all mapped devices:

sudo cryptsetup status
  • Example: sudo cryptsetup status
  • Explanation: Shows the status of all active cryptsetup mappings, including the underlying device, mapped name, cipher, and key size.

Change passphrase (interactive):

sudo cryptsetup luksChangeKey /dev/sdXN
  • Example: sudo cryptsetup luksChangeKey /dev/sdb1
  • Explanation: Prompts for the old passphrase and then the new passphrase to change it. This is equivalent to removing the old key and adding a new one.

Set volume integrity (for dm-integrity):

sudo cryptsetup open --integrity <cipher> --integrity-key-size <key_size> /dev/sdXN <mapper_name>
  • Example: sudo cryptsetup open --integrity aes-xts-plain64 --integrity-key-size 512 /dev/sdc1 secure_data_with_integrity
  • Explanation: Opens the device with data integrity checks enabled using the specified cipher and key size. Requires a LUKS header created with appropriate integrity settings or a device that supports it.

Common Patterns

Encrypting a new drive for use as a home directory:

  1. Format the target partition:
    sudo cryptsetup luksFormat /dev/sdXN
  2. Open the encrypted partition:
    sudo cryptsetup open /dev/sdXN crypt_home
  3. Create a filesystem on the mapped device:
    sudo mkfs.ext4 /dev/mapper/crypt_home
  4. Mount the filesystem:
    sudo mount /dev/mapper/crypt_home /mnt/temp_home
  5. Copy existing home data (if any):
    sudo rsync -avx /home/ /mnt/temp_home/
  6. Update /etc/fstab to mount on boot: Add a line like: /dev/mapper/crypt_home /home ext4 defaults 0 2 (Note: You’ll likely need a mechanism to prompt for the passphrase on boot, e.g., using crypttab and potentially systemd-cryptsetup-generator).
  7. Close the temporary mount:
    sudo umount /mnt/temp_home
sudo cryptsetup close crypt_home
  8. Configure boot to unlock on startup (using /etc/crypttab): Add a line to /etc/crypttab (e.g., /dev/sdXN /dev/sdXN none luks or /dev/sdXN UUID=<UUID_of_sdXN> /path/to/keyfile luks,keyscript=/lib/cryptsetup/scripts/passdev for keyfile).

Automating LUKS unlock on boot (using a key file):

  1. Create a key file:
    sudo dd if=/dev/urandom of=/etc/cryptsetup-keys/my_drive.key bs=512 count=1
sudo chmod 0400 /etc/cryptsetup-keys/my_drive.key
  2. Add the key file to the LUKS volume:
    sudo cryptsetup luksAddKey /dev/sdXN /etc/cryptsetup-keys/my_drive.key
    (You’ll be prompted for a valid passphrase to authorize this.)
  3. Edit /etc/crypttab: Find the UUID of /dev/sdXN (sudo blkid -s UUID -o value /dev/sdXN). Add a line like: UUID=<UUID_of_sdXN> /etc/cryptsetup-keys/my_drive.key luks,discard (The discard option is for SSDs and can improve performance but has security implications if not managed carefully).
  4. Update initramfs (if necessary):
    sudo update-initramfs -u -k all
    (Or dracut -f on Fedora/RHEL-based systems).
  5. Reboot to test.

Encrypting a swap partition:

  1. Create a swap partition (e.g., /dev/sdXN).
  2. Format it for LUKS:
    sudo cryptsetup luksFormat /dev/sdXN
  3. Open the LUKS volume:
    sudo cryptsetup open /dev/sdXN crypt_swap
  4. Create a swap area:
    sudo mkswap /dev/mapper/crypt_swap
  5. Enable the swap:
    sudo swapon /dev/mapper/crypt_swap
  6. Add to /etc/fstab: Add a line like: /dev/mapper/crypt_swap none swap sw 0 0
  7. Consider adding to /etc/crypttab for automatic unlocking on boot, similar to encrypting a data partition.

Checking the integrity of an encrypted volume (after mounting): This is typically done at the filesystem level or by using dm-integrity features if set up during LUKS creation. cryptsetup itself doesn’t have a direct "check integrity" command for data once it’s decrypted.

Gotchas

  • Data Loss: cryptsetup luksFormat is destructive. All data on the target device will be erased. Double-check the device name (/dev/sdXN).
  • Passphrase Strength: A weak passphrase makes your encryption trivial to crack. Use strong, unique passphrases.
  • Forgetting Passphrases: If you forget your passphrase and don’t have a recovery key or backup, your data is irrecoverably lost.
  • Key File Security: If you use a key file to unlock a LUKS volume, the security of your data relies entirely on the security of that key file. Protect it rigorously (permissions, location).
  • Header Corruption: The LUKS header contains critical metadata. If it’s corrupted, recovery can be very difficult or impossible. Back up your LUKS header if possible (e.g., cryptsetup luksHeaderBackup /dev/sdXN --header-backup-file /path/to/backup.img).
  • Resizing Complexity: Resizing LUKS volumes requires multiple steps and careful ordering. Always resize the underlying partition before resizing the LUKS container with cryptsetup resize.
  • Performance: Encryption adds CPU overhead. Modern CPUs with AES-NI instructions significantly mitigate this. Older CPUs might experience noticeable performance degradation.
  • discard Option: Using the discard option for SSDs can improve performance but may have security implications as it can reveal which blocks are in use. Consider the trade-offs.
  • /dev/mapper/ Naming: Ensure your chosen mapper names (<mapper_name>) are unique and descriptive. They become the device nodes for your decrypted data.