Skip to content

cryptsetup.md

Latest commit

 

History

History
1118 lines (820 loc) · 25.6 KB

cryptsetup.md

File metadata and controls

1118 lines (820 loc) · 25.6 KB
Raw
title cryptsetup - LUKS Encryption Management
description Complete guide to cryptsetup - LUKS Encryption Management
category Storage
tags
storage
disk management
lvm
partitioning
systemd
difficulty beginner
last_updated 2026-06-06
related_commands
dm-crypt
dmsetup
luksmeta
clevis
systemd-cryptenroll

cryptsetup - LUKS Encryption Management

Overview

cryptsetup is the standard tool for setting up encrypted filesystems using dm-crypt and LUKS (Linux Unified Key Setup). It provides secure data encryption at the block device level, supporting multiple encryption algorithms, key management, and various encryption modes. cryptsetup is essential for protecting data at rest on Linux systems.

Modern Features (LUKS2, kernel 5.x+):

  • LUKS2 format (default since cryptsetup 2.x)
  • Argon2 PBKDF (GPU-resistant key derivation)
  • TPM2 integration for automatic unlocking
  • FIDO2/U2F hardware token support
  • Clevis/Tang network-based key escrow
  • Better metadata protection and recovery
  • Multiple independent keystores

Target Platforms:

  • RHEL 8/9/10, CentOS Stream 8/9
  • Ubuntu 22.04 LTS, 24.04 LTS
  • SUSE SLES 15, Leap 15+
  • Kernel 5.x, 6.x (dm-crypt/dm-integrity)

Installation

Package Managers

# Debian/Ubuntu (cryptsetup 2.x+)
apt-get update
apt-get install cryptsetup cryptsetup-bin

# RHEL/CentOS/Fedora (cryptsetup 2.x+)
dnf install cryptsetup cryptsetup-reencrypt

# For TPM2 support
dnf install clevis clevis-luks clevis-dracut tpm2-tools

# SUSE/openSUSE
zypper install cryptsetup

# Arch Linux
pacman -S cryptsetup

# Verify version (should be 2.x or higher)
cryptsetup --version
# cryptsetup 2.6.1

Basic Syntax

cryptsetup [OPTIONS] ACTION [ACTION-SPECIFIC-OPTIONS] DEVICE [KEY FILE]

LUKS Operations

Format LUKS Volume

# Create LUKS2 encrypted volume (default in cryptsetup 2.x+)
cryptsetup luksFormat /dev/sdb1

# LUKS1 format (legacy compatibility only, not recommended)
cryptsetup luksFormat --type luks1 /dev/sdb1

# LUKS2 with Argon2 PBKDF (recommended, default)
cryptsetup luksFormat \
  --type luks2 \
  --cipher aes-xts-plain64 \
  --key-size 512 \
  --hash sha512 \
  --pbkdf argon2id \
  --pbkdf-memory 1048576 \
  --pbkdf-parallel 4 \
  /dev/sdb1

# With key file instead of passphrase
cryptsetup luksFormat /dev/sdb1 /path/to/keyfile

# Non-interactive with passphrase from stdin
echo "mypassphrase" | cryptsetup luksFormat /dev/sdb1 -

# LUKS2 with sector integrity (dm-integrity, kernel 4.12+)
cryptsetup luksFormat \
  --type luks2 \
  --integrity hmac-sha256 \
  --sector-size 4096 \
  /dev/sdb1

# For NVMe drives with 4K native sectors
cryptsetup luksFormat \
  --type luks2 \
  --sector-size 4096 \
  --cipher aes-xts-plain64 \
  --key-size 512 \
  /dev/nvme0n1p1

# Maximum security LUKS2 setup (modern systems)
cryptsetup luksFormat \
  --type luks2 \
  --cipher aes-xts-plain64 \
  --key-size 512 \
  --hash sha512 \
  --pbkdf argon2id \
  --pbkdf-memory 2097152 \
  --pbkdf-parallel 4 \
  --pbkdf-force-iterations 10 \
  --use-random \
  /dev/sdb1

Open LUKS Volume

# Open LUKS volume
cryptsetup luksOpen /dev/sdb1 encrypted_data

# Device mapper name will be /dev/mapper/encrypted_data

# Open with key file
cryptsetup luksOpen /dev/sdb1 encrypted_data --key-file=/path/to/keyfile

# Open read-only
cryptsetup luksOpen --readonly /dev/sdb1 encrypted_data

# Open and use specific key slot
cryptsetup luksOpen --key-slot 0 /dev/sdb1 encrypted_data

# Open with test mode (don't activate)
cryptsetup luksOpen --test-passphrase /dev/sdb1

# Open with header from separate file
cryptsetup luksOpen /dev/sdb1 encrypted_data --header=/path/to/header.img

Close LUKS Volume

# Close encrypted volume
cryptsetup luksClose encrypted_data

# Alternative command
cryptsetup close encrypted_data

# Close multiple volumes
cryptsetup close encrypted_data1 encrypted_data2

# Force close (unmount first if needed)
umount /dev/mapper/encrypted_data
cryptsetup luksClose encrypted_data

LUKS Key Management

# Add new key (slot)
cryptsetup luksAddKey /dev/sdb1

# Add key from file
cryptsetup luksAddKey /dev/sdb1 /path/to/new_keyfile

# Add key to specific slot
cryptsetup luksAddKey --key-slot 1 /dev/sdb1

# Change existing passphrase
cryptsetup luksChangeKey /dev/sdb1

# Remove key from slot
cryptsetup luksRemoveKey /dev/sdb1

# Kill specific key slot
cryptsetup luksKillSlot /dev/sdb1 1

# Test passphrase validity
cryptsetup luksOpen --test-passphrase /dev/sdb1
echo $?  # 0 = valid, non-zero = invalid

LUKS Header Operations

# Backup LUKS header
cryptsetup luksHeaderBackup /dev/sdb1 --header-backup-file=/backup/sdb1.header

# Restore LUKS header
cryptsetup luksHeaderRestore /dev/sdb1 --header-backup-file=/backup/sdb1.header

# Dump header information
cryptsetup luksDump /dev/sdb1

# Get UUID
cryptsetup luksUUID /dev/sdb1

# Change UUID
cryptsetup luksUUID --uuid=12345678-1234-1234-1234-123456789012 /dev/sdb1

# Verify header integrity
cryptsetup luksDump /dev/sdb1 | grep -i "payload offset"

Plain dm-crypt (No LUKS)

Create Plain Encrypted Device

# Open with plain mode
cryptsetup open --type plain /dev/sdb1 plain_encrypted

# With specific cipher and key size
cryptsetup open --type plain \
  --cipher aes-xts-plain64 \
  --key-size 512 \
  --hash sha512 \
  /dev/sdb1 plain_encrypted

# With offset
cryptsetup open --type plain --offset 1024 /dev/sdb1 plain_encrypted

# Note: Plain mode has no header, password must be exactly the same
# No password recovery possible!

Complete Encryption Workflows

Encrypt New Partition

# 1. Create partition if needed
sgdisk --new=1:0:0 /dev/sdb

# 2. Wipe partition (recommended)
dd if=/dev/zero of=/dev/sdb1 bs=1M status=progress

# 3. Format as LUKS
cryptsetup luksFormat /dev/sdb1

# 4. Open encrypted volume
cryptsetup luksOpen /dev/sdb1 encrypted_data

# 5. Create filesystem
mkfs.ext4 /dev/mapper/encrypted_data

# 6. Mount
mount /dev/mapper/encrypted_data /mnt/secure

# 7. Use...

# 8. Cleanup
umount /mnt/secure
cryptsetup luksClose encrypted_data

Encrypted Root Filesystem

# Partition layout
sgdisk --new=1:0:+512M --typecode=1:ef00 /dev/sda  # EFI
sgdisk --new=2:0:0 --typecode=2:8300 /dev/sda      # Root

# Format boot partition
mkfs.vfat -F32 /dev/sda1

# Encrypt root
cryptsetup luksFormat /dev/sda2
cryptsetup luksOpen /dev/sda2 cryptroot

# Create filesystem
mkfs.ext4 /dev/mapper/cryptroot

# Install system
mount /dev/mapper/cryptroot /mnt
mkdir /mnt/boot
mount /dev/sda1 /mnt/boot

# ... install OS ...

# Configure crypttab
echo "cryptroot UUID=$(blkid -s UUID -o value /dev/sda2) none luks" >> /mnt/etc/crypttab

# Update initramfs to include cryptsetup
chroot /mnt update-initramfs -u

LVM on LUKS

# Encrypt partition
cryptsetup luksFormat /dev/sdb1
cryptsetup luksOpen /dev/sdb1 cryptlvm

# Create LVM on encrypted device
pvcreate /dev/mapper/cryptlvm
vgcreate vg_encrypted /dev/mapper/cryptlvm

# Create logical volumes
lvcreate -L 50G -n lv_root vg_encrypted
lvcreate -L 100G -n lv_home vg_encrypted
lvcreate -l 100%FREE -n lv_data vg_encrypted

# Format filesystems
mkfs.ext4 /dev/vg_encrypted/lv_root
mkfs.ext4 /dev/vg_encrypted/lv_home
mkfs.ext4 /dev/vg_encrypted/lv_data

# Mount
mount /dev/vg_encrypted/lv_root /mnt
mkdir /mnt/home
mount /dev/vg_encrypted/lv_home /mnt/home

# Cleanup
umount /mnt/home /mnt
vgchange -an vg_encrypted
cryptsetup luksClose cryptlvm

LUKS on LVM

# Create LVM first
pvcreate /dev/sdb
vgcreate vg_data /dev/sdb
lvcreate -L 100G -n lv_secure vg_data

# Encrypt LV
cryptsetup luksFormat /dev/vg_data/lv_secure
cryptsetup luksOpen /dev/vg_data/lv_secure encrypted_lv

# Format and use
mkfs.ext4 /dev/mapper/encrypted_lv
mount /dev/mapper/encrypted_lv /mnt/secure

# Cleanup
umount /mnt/secure
cryptsetup luksClose encrypted_lv

LUKS2 Specific Features

LUKS2 Tokens (Modern Authentication)

# LUKS2 supports multiple token types for authentication

# Add systemd-tpm2 token
systemd-cryptenroll --tpm2-device=auto /dev/sdb1

# Add systemd-fido2 token
systemd-cryptenroll --fido2-device=auto /dev/sdb1

# Add systemd-pkcs11 token
systemd-cryptenroll --pkcs11-token-uri=auto /dev/sdb1

# List all tokens
cryptsetup luksDump /dev/sdb1 | grep -A 5 "Tokens:"

# Remove specific token
cryptsetup token remove --token-id 0 /dev/sdb1

# Export token to JSON
cryptsetup token export --token-id 0 /dev/sdb1

# Import token from JSON
cryptsetup token import --token-id 0 /dev/sdb1 < token.json

LUKS2 Keyslot Priorities and Labels

# Set keyslot priority (1=lowest, 3=highest)
cryptsetup config --priority prefer /dev/sdb1 --key-slot 0
cryptsetup config --priority normal /dev/sdb1 --key-slot 1
cryptsetup config --priority ignore /dev/sdb1 --key-slot 2

# Label keyslots for identification
cryptsetup config --keyslot-cipher aes-xts-plain64 \
  --keyslot-key-size 512 /dev/sdb1 --key-slot 0

# Set keyslot description
cryptsetup token add --token-id 0 \
  --key-description "TPM2 auto-unlock" /dev/sdb1

Online Reencryption (LUKS2)

# LUKS2 supports online reencryption (no downtime)

# Change cipher algorithm (online)
cryptsetup reencrypt /dev/sdb1 \
  --cipher aes-xts-plain64 \
  --key-size 512 \
  --reduce-device-size 32M

# Change PBKDF (key derivation function)
cryptsetup luksChangeKey /dev/sdb1 \
  --pbkdf argon2id \
  --pbkdf-memory 1048576

# Encrypt existing plain device to LUKS2 (online)
cryptsetup reencrypt /dev/sdb1 \
  --encrypt \
  --reduce-device-size 32M

# Monitor reencryption progress
cryptsetup status /dev/mapper/luks-device

LUKS2 Integrity Protection

# Create LUKS2 with authenticated encryption (AEAD)
cryptsetup luksFormat \
  --type luks2 \
  --cipher aes-xts-plain64 \
  --integrity hmac-sha256 \
  --integrity-no-wipe \
  /dev/sdb1

# Supported integrity algorithms:
# - hmac-sha256
# - hmac-sha512
# - poly1305
# - none

# Check integrity status
cryptsetup luksDump /dev/sdb1 | grep -i integrity

# Verify data integrity
cryptsetup open --test-passphrase /dev/sdb1

NVMe and SSD Optimizations

# LUKS2 on NVMe with optimal sector size
cryptsetup luksFormat \
  --type luks2 \
  --sector-size 4096 \
  --cipher aes-xts-plain64 \
  --key-size 512 \
  --pbkdf argon2id \
  /dev/nvme0n1p1

# Enable TRIM/discard for SSDs
cryptsetup luksFormat --type luks2 /dev/sdb1
cryptsetup open --allow-discards /dev/sdb1 encrypted_ssd

# Or set persistent discard in /etc/crypttab
# encrypted_ssd UUID=xxx none luks,discard

# Performance tuning for NVMe
cryptsetup open /dev/nvme0n1p1 nvme_encrypted \
  --perf-same_cpu_crypt \
  --perf-submit_from_crypt_cpus \
  --allow-discards

# Check performance settings
dmsetup table --showkeys /dev/mapper/nvme_encrypted

Advanced Features

Detached LUKS Header

# Create header file
dd if=/dev/zero of=/secure/header.img bs=16M count=1

# Format with detached header
cryptsetup luksFormat /dev/sdb1 --header=/secure/header.img

# Open with detached header
cryptsetup luksOpen /dev/sdb1 encrypted_data --header=/secure/header.img

# Advantages:
# - Hidden encryption (device looks like random data)
# - Header stored separately (more secure)
# - Plausible deniability

# Backup header
cp /secure/header.img /backup/header.img.backup

Multiple Key Slots

# LUKS supports up to 8 key slots (LUKS1) or 32 (LUKS2)

# Add multiple keys for different users
cryptsetup luksAddKey /dev/sdb1  # Slot 1
cryptsetup luksAddKey /dev/sdb1  # Slot 2
cryptsetup luksAddKey /dev/sdb1  # Slot 3

# Add key from file for automated unlocking
cryptsetup luksAddKey /dev/sdb1 /root/keyfile

# View used slots
cryptsetup luksDump /dev/sdb1 | grep "Key Slot"

# Remove specific slot
cryptsetup luksKillSlot /dev/sdb1 2

# Emergency: Kill all slots except one
# (DANGEROUS - can lock you out!)
for slot in {0..7}; do
  cryptsetup luksKillSlot /dev/sdb1 $slot || true
done

Key Files

# Generate random key file
dd if=/dev/urandom of=/root/luks.key bs=1 count=4096
chmod 600 /root/luks.key

# Format with key file
cryptsetup luksFormat /dev/sdb1 /root/luks.key

# Open with key file
cryptsetup luksOpen /dev/sdb1 encrypted_data --key-file=/root/luks.key

# Add passphrase in addition to key file
cryptsetup luksAddKey /dev/sdb1 --key-file=/root/luks.key

# Automated mounting with key file in /etc/crypttab
echo "encrypted_data UUID=$(blkid -s UUID -o value /dev/sdb1) /root/luks.key luks" >> /etc/crypttab

Benchmark Ciphers

# Benchmark available ciphers
cryptsetup benchmark

# Example output:
# aes-cbc        256 bit |  1234.5 MiB/s |  2345.6 MiB/s
# aes-xts        256 bit |  2345.6 MiB/s |  3456.7 MiB/s
# serpent-xts    256 bit |   345.6 MiB/s |   456.7 MiB/s

# Benchmark specific cipher
cryptsetup benchmark --cipher aes-xts-plain64 --key-size 512

# Use fastest cipher from benchmark
# (aes-xts-plain64 is usually best on modern CPUs with AES-NI)

Resize Operations

Resize Encrypted Volume

# Resize partition first (example: grow)
parted /dev/sdb resizepart 1 200GB

# Close encrypted volume
umount /dev/mapper/encrypted_data
cryptsetup luksClose encrypted_data

# Resize LUKS container
cryptsetup resize encrypted_data
# Or specify size
cryptsetup resize encrypted_data --size 200G

# Reopen
cryptsetup luksOpen /dev/sdb1 encrypted_data

# Resize filesystem
resize2fs /dev/mapper/encrypted_data  # ext4
xfs_growfs /dev/mapper/encrypted_data  # xfs

# Remount
mount /dev/mapper/encrypted_data /mnt/data

Shrink Encrypted Volume

# Must shrink filesystem first
umount /dev/mapper/encrypted_data
e2fsck -f /dev/mapper/encrypted_data
resize2fs /dev/mapper/encrypted_data 150G

# Close and resize LUKS
cryptsetup luksClose encrypted_data
cryptsetup resize /dev/sdb1 --size $((150 * 1024 * 1024))  # In 512-byte sectors

# Resize partition last
parted /dev/sdb resizepart 1 150GB

Security Considerations

Secure Key Destruction

# Remove all keys (makes data unrecoverable)
for slot in {0..7}; do
  cryptsetup luksKillSlot /dev/sdb1 $slot 2>/dev/null || true
done

# Verify no slots active
cryptsetup luksDump /dev/sdb1 | grep "Key Slot"

# Wipe LUKS header
cryptsetup luksErase /dev/sdb1

# Additional secure wipe of first MB
dd if=/dev/urandom of=/dev/sdb1 bs=1M count=10

Strong Encryption Setup

# Use strongest available encryption
cryptsetup luksFormat \
  --type luks2 \
  --cipher aes-xts-plain64 \
  --key-size 512 \
  --hash sha512 \
  --iter-time 5000 \
  --pbkdf argon2id \
  --use-random \
  /dev/sdb1

# LUKS2 advantages:
# - Argon2 PBKDF (resistant to GPU attacks)
# - Multiple digests
# - Better header protection

Key File Security

# Generate strong key file
dd if=/dev/random of=/root/luks.key bs=1 count=4096

# Secure permissions
chmod 400 /root/luks.key
chown root:root /root/luks.key

# Store on separate device (USB, TPM, etc.)
# Never store key file on encrypted device!

# For automated boot, store key in initramfs
# Add to /etc/cryptsetup-initramfs/conf-hook:
# KEYFILE_PATTERN="/root/luks.key"
update-initramfs -u

System Integration

/etc/crypttab Configuration

# Format: name device keyfile options

# Basic entry with passphrase prompt
encrypted_data /dev/sdb1 none luks

# With key file
encrypted_data /dev/sdb1 /root/luks.key luks

# With UUID (recommended)
encrypted_data UUID=12345678-1234-1234-1234-123456789012 /root/luks.key luks

# With options
encrypted_data UUID=12345678... /root/luks.key luks,discard,timeout=60

# Multiple entries
encrypted_data1 /dev/sdb1 none luks
encrypted_data2 /dev/sdc1 none luks
encrypted_swap /dev/sdd1 /dev/urandom swap,cipher=aes-xts-plain64

Systemd Integration

# Systemd automatically handles /etc/crypttab

# Check status
systemctl status systemd-cryptsetup@encrypted_data.service

# Manual operations
systemctl start systemd-cryptsetup@encrypted_data.service
systemctl stop systemd-cryptsetup@encrypted_data.service

# Generate passphrase at boot
systemd-ask-password --id=cryptsetup

# Use TPM2 for automatic unlocking
cryptsetup luksFormat --type luks2 /dev/sdb1
systemd-cryptenroll /dev/sdb1 --tpm2-device=auto

Automated Unlocking (Modern Methods)

# Method 1: TPM2 integration (RHEL 8+, Ubuntu 20.04+)
# Bind LUKS2 volume to TPM2 chip for automatic unlock
systemd-cryptenroll --tpm2-device=auto /dev/sdb1

# TPM2 with PCR (Platform Configuration Register) binding
# PCRs 0,2,4,7 = firmware, boot loader, drivers, secure boot
systemd-cryptenroll --tpm2-device=auto \
  --tpm2-pcrs=0+2+4+7 \
  /dev/sdb1

# TPM2 with PIN
systemd-cryptenroll --tpm2-device=auto \
  --tpm2-with-pin=yes \
  /dev/sdb1

# Method 2: FIDO2/U2F hardware token (YubiKey, etc.)
systemd-cryptenroll --fido2-device=auto /dev/sdb1

# FIDO2 with PIN requirement
systemd-cryptenroll --fido2-device=auto \
  --fido2-with-user-presence=yes \
  --fido2-with-user-verification=yes \
  /dev/sdb1

# Method 3: Network-based unlocking (Tang/Clevis)
# Install Clevis
dnf install clevis clevis-luks clevis-dracut

# Bind to Tang server (network-bound disk encryption)
clevis luks bind -d /dev/sdb1 tang '{"url":"https://tang.example.com"}'

# Unbind Tang key
clevis luks unbind -d /dev/sdb1 -s 1

# Method 4: Key file in initramfs (traditional)
echo "KEYFILE_PATTERN=/root/*.key" >> /etc/cryptsetup-initramfs/conf-hook
update-initramfs -u

# Method 5: PKCS#11 smartcard/token
systemd-cryptenroll --pkcs11-token-uri=auto /dev/sdb1

# List enrolled methods
systemd-cryptenroll /dev/sdb1

# Remove specific enrollment
systemd-cryptenroll --wipe-slot=tpm2 /dev/sdb1

TPM2 Integration Details

# Check TPM2 availability
systemd-cryptenroll --tpm2-device=list

# Example output:
# /dev/tpmrm0

# Check current PCR values
tpm2_pcrread

# Test TPM2 unlock without enrollment
systemd-cryptenroll --tpm2-device=auto \
  --tpm2-pcrs= \
  /dev/sdb1

# Production TPM2 setup with PCR policy
# Locks to specific boot state
systemd-cryptenroll --tpm2-device=/dev/tpmrm0 \
  --tpm2-pcrs=0+1+2+3+7 \
  --tpm2-with-pin=no \
  /dev/sdb1

# Update initramfs to use TPM2
# Debian/Ubuntu
echo 'RESUME=none' >> /etc/initramfs-tools/conf.d/resume
update-initramfs -u -k all

# RHEL/Fedora (automatic with clevis-dracut)
dracut -f

# Verify systemd-cryptsetup service
systemctl status systemd-cryptsetup@luks*.service

Clevis/Tang Network Bound Encryption

# Setup Tang server (on separate system)
dnf install tang
systemctl enable --now tangd.socket

# Get Tang server thumbprint
curl -s http://tang.example.com/adv | \
  jose fmt -j- -Og payload -o- | \
  jose jwk use -i- -r -u verify -o- | \
  jose jwk thp -i- -a S256

# Bind LUKS volume to Tang server with thumbprint verification
clevis luks bind -d /dev/sdb1 tang \
  '{"url":"http://tang.example.com","thp":"THUMBPRINT_HERE"}'

# Multiple Tang servers for redundancy (Shamir Secret Sharing)
clevis luks bind -d /dev/sdb1 sss \
  '{"t":2,"pins":{"tang":[
    {"url":"http://tang1.example.com"},
    {"url":"http://tang2.example.com"},
    {"url":"http://tang3.example.com"}
  ]}}'

# Requires 2 of 3 Tang servers to unlock

# Update initramfs with Clevis
dracut -f --regenerate-all

# Test unlock
clevis luks unlock -d /dev/sdb1 -n test
cryptsetup close test

Monitoring and Maintenance

Status Checking

# Check if device is encrypted
cryptsetup isLuks /dev/sdb1 && echo "LUKS encrypted"

# Get encryption status
cryptsetup status encrypted_data

# Dump LUKS header
cryptsetup luksDump /dev/sdb1

# Check which devices are encrypted
lsblk -o NAME,TYPE,FSTYPE,SIZE,MOUNTPOINT | grep crypto

# List active encrypted devices
dmsetup ls --target crypt

Performance Monitoring

# Check encryption overhead
# Plain read
dd if=/dev/sdb of=/dev/null bs=1M count=1000

# Encrypted read
dd if=/dev/mapper/encrypted_data of=/dev/null bs=1M count=1000

# Monitor I/O
iostat -x /dev/mapper/encrypted_data 1

# Check CPU usage (encryption)
top -b -n 1 | grep -E "kworker|dmcrypt"

Health Checks

# Verify header integrity
cryptsetup luksDump /dev/sdb1 > /dev/null
echo $?  # 0 = OK

# Test passphrase without opening
cryptsetup luksOpen --test-passphrase /dev/sdb1

# Check for weak keys (if slots use old algorithms)
cryptsetup luksDump /dev/sdb1 | grep -E "PBKDF|Iterations"

# Verify all key slots
for slot in {0..7}; do
  echo -n "Slot $slot: "
  cryptsetup luksDump /dev/sdb1 | grep -A 1 "Key Slot $slot" | grep "ENABLED" && echo "Active" || echo "Disabled"
done

Troubleshooting

Cannot Open Volume

# Check if device is LUKS
cryptsetup isLuks /dev/sdb1

# Check LUKS version
cryptsetup luksDump /dev/sdb1 | grep "Version"

# Test passphrase
cryptsetup luksOpen --test-passphrase /dev/sdb1

# Check for header corruption
cryptsetup luksDump /dev/sdb1

# Try recovery from header backup
cryptsetup luksHeaderRestore /dev/sdb1 --header-backup-file=/backup/header.img

Device Busy Errors

# Find what's using the device
lsof /dev/mapper/encrypted_data
fuser -mv /dev/mapper/encrypted_data

# Check mounts
mount | grep encrypted_data

# Unmount
umount /dev/mapper/encrypted_data

# If LVM, deactivate
vgchange -an vg_name

# Then close
cryptsetup luksClose encrypted_data

Performance Issues

# Check if AES-NI is available
grep -m1 -o aes /proc/cpuinfo

# Load AES-NI module if available
modprobe aesni-intel

# Check which cipher is in use
cryptsetup status encrypted_data | grep cipher

# Consider switching to AES-XTS if not already
# (requires reformatting)

# Enable TRIM/discard for SSDs
cryptsetup --allow-discards luksOpen /dev/sdb1 encrypted_ssd

Migration and Conversion

LUKS1 to LUKS2

# Backup first!
cryptsetup luksHeaderBackup /dev/sdb1 --header-backup-file=/backup/luks1.header

# Convert to LUKS2
cryptsetup convert /dev/sdb1 --type luks2

# Verify
cryptsetup luksDump /dev/sdb1 | grep "Version"

# Note: Conversion is one-way without restore

Change Encryption Algorithm

# Cannot change algorithm in-place
# Must backup data, reformat, restore

# 1. Backup data
mount /dev/mapper/encrypted_data /mnt/old
rsync -av /mnt/old/ /backup/encrypted_backup/

# 2. Close and reformat
umount /mnt/old
cryptsetup luksClose encrypted_data
cryptsetup luksFormat --cipher serpent-xts-plain64 --key-size 512 /dev/sdb1

# 3. Restore data
cryptsetup luksOpen /dev/sdb1 encrypted_data
mkfs.ext4 /dev/mapper/encrypted_data
mount /dev/mapper/encrypted_data /mnt/new
rsync -av /backup/encrypted_backup/ /mnt/new/

Backup Strategies

Complete Backup

# Method 1: Backup encrypted (can't access without key)
dd if=/dev/sdb1 of=/backup/encrypted.img bs=1M status=progress

# Method 2: Backup decrypted data
cryptsetup luksOpen /dev/sdb1 encrypted_data
dd if=/dev/mapper/encrypted_data of=/backup/decrypted.img bs=1M status=progress
cryptsetup luksClose encrypted_data

# Method 3: Filesystem-level backup
cryptsetup luksOpen /dev/sdb1 encrypted_data
mount /dev/mapper/encrypted_data /mnt/data
rsync -av /mnt/data/ /backup/data/
umount /mnt/data
cryptsetup luksClose encrypted_data

Header-Only Backup

# Backup LUKS header (small, quick)
cryptsetup luksHeaderBackup /dev/sdb1 --header-backup-file=/backup/luks_header_$(date +%Y%m%d).img

# Encrypt header backup
gpg -c /backup/luks_header_$(date +%Y%m%d).img

# Store securely offline

Related Commands

  • dm-crypt - Device mapper crypto target
  • dmsetup - Device mapper management
  • luksmeta - LUKS metadata management
  • clevis - Automated decryption framework
  • systemd-cryptenroll - Enroll PKCS11, FIDO2, TPM2 tokens
  • veracrypt - Cross-platform encryption (alternative)

Exit Codes

# 0 - Success
# 1 - Wrong parameters
# 2 - No permission
# 3 - Out of memory
# 4 - Wrong device specified
# 5 - Device already exists or busy

# Example
if cryptsetup luksOpen /dev/sdb1 encrypted_data; then
  echo "Opened successfully"
else
  echo "Failed with code $?"
fi

Examples Collection

Example 1: Simple Encrypted USB Drive

# Format
cryptsetup luksFormat /dev/sdb1

# Open
cryptsetup luksOpen /dev/sdb1 usb_encrypted

# Format filesystem
mkfs.ext4 -L "Encrypted USB" /dev/mapper/usb_encrypted

# Mount
mount /dev/mapper/usb_encrypted /mnt/usb

# Use...

# Cleanup
umount /mnt/usb
cryptsetup luksClose usb_encrypted

Example 2: Automated Server Volume

# Create key file
dd if=/dev/random of=/root/server.key bs=1 count=4096
chmod 400 /root/server.key

# Format and add key
cryptsetup luksFormat /dev/sdb1
cryptsetup luksAddKey /dev/sdb1 /root/server.key

# Configure /etc/crypttab
echo "server_data UUID=$(blkid -s UUID -o value /dev/sdb1) /root/server.key luks" >> /etc/crypttab

# Configure /etc/fstab
echo "/dev/mapper/server_data /srv/data ext4 defaults 0 2" >> /etc/fstab

# Reboot test
reboot

Example 3: Maximum Security Setup

# Strongest encryption
cryptsetup luksFormat \
  --type luks2 \
  --cipher aes-xts-plain64 \
  --key-size 512 \
  --hash sha512 \
  --pbkdf argon2id \
  --iter-time 5000 \
  --use-random \
  /dev/sdb1

# Detached header
dd if=/dev/zero of=/secure/header.img bs=16M count=1
cryptsetup luksFormat /dev/sdb1 --header=/secure/header.img

# Multiple authentication methods
cryptsetup luksAddKey /dev/sdb1 --header=/secure/header.img  # Passphrase
cryptsetup luksAddKey /dev/sdb1 --header=/secure/header.img /root/key1.bin
cryptsetup luksAddKey /dev/sdb1 --header=/secure/header.img /root/key2.bin

# Open and use
cryptsetup luksOpen /dev/sdb1 secure_data --header=/secure/header.img

Summary

cryptsetup is the standard Linux tool for disk encryption, providing robust protection for data at rest using dm-crypt and LUKS. It supports various encryption algorithms, multiple authentication methods, and integrates well with system boot processes. Understanding cryptsetup is essential for implementing security best practices, protecting sensitive data, and meeting compliance requirements in Linux environments.