cryptsetup

Initialize a LUKS volume with a passphrase (overwrites all data on the partition)

$ cryptsetup luksFormat [/dev/sdXY]

$ cryptsetup open [/dev/sdXY] [mapping_name]

$ cryptsetup status [mapping_name]

$ cryptsetup close [mapping_name]

$ cryptsetup luksChangeKey [/dev/sdXY]

cryptsetup [OPTIONS] <command> <device> [<name>] [<args>...]

Common invocation examples:
cryptsetup luksFormat <device>
cryptsetup open <device> [<name>] [--type <type>]
cryptsetup close <name>

--verbose, -v
    Show more detailed information during command execution.

--debug, -d
    Show debug messages for problem diagnosis.

--quiet, -q
    Suppress all non-error messages.

--batch-mode, -y
    Never ask for user input. Operations requiring input will fail.

--tries , -S
    Specify the number of tries for password input.

--timeout , -T
    Specify the timeout for password input in seconds.

--cipher , -c
    Specify the encryption cipher and mode (e.g., aes-xts-plain64).

--hash , -h
    Specify the hash algorithm (e.g., sha256) for PBKDF.

--key-size , -s
    Specify the encryption key size in bits for the master key.

--iter-time , -i
    PBKDF iteration time for passphrase processing in milliseconds.

--key-file , -l
    Read the key (passphrase or binary key) from the specified file instead of stdin.

--pbkdf
    Specify the PBKDF algorithm to use (e.g., argon2i, pbkdf2).

--pbkdf-memory-cost
    Memory cost for PBKDF (e.g., Argon2). Higher values provide better security but require more RAM.

--header-backup-file
    Specify a file for LUKS header backup or restore operations.

--allow-discards
    Enable TRIM/DISCARD support for the mapped device. Can have security implications.

--type
    Specify the type of encrypted device (e.g., luks, plain, veracrypt).

cryptsetup is a powerful command-line utility used to manage encrypted block devices, primarily leveraging the dm-crypt kernel module and the LUKS (Linux Unified Key Setup) on-disk format. It provides a user-friendly frontend to dm-crypt, simplifying complex encryption tasks.

Its main purpose is to create, open, close, and manage LUKS encrypted volumes, which are widely used for full disk encryption, encrypted partitions, and portable storage devices. LUKS offers a standardized way to store encryption metadata, allowing for multiple passphrases/keys for the same volume, passphrase revocation, and effective key management.

cryptsetup also supports plain dm-crypt (without LUKS header), TrueCrypt/VeraCrypt compatible volumes, and loop-AES volumes. It does not handle filesystem operations directly but rather provides an unencrypted block device on top of an encrypted one, which can then be formatted and mounted like any other disk. It is an essential tool for data security and privacy on Linux systems.

Using cryptsetup incorrectly can lead to irreversible data loss. Always back up important data, especially the LUKS header, before performing any operations that modify the encryption metadata or the device itself. Strong passphrases and robust PBKDF parameters are crucial for security. Be aware that cryptsetup operates on block devices; it does not manage filesystems directly. Performance can be impacted by the chosen cipher, key size, and underlying hardware. Enabling TRIM/DISCARD (--allow-discards) can have security implications by revealing data patterns if not handled carefully, potentially making erased data recoverable by an attacker.

cryptsetup is an action-oriented command-line tool. Here are some of its most commonly used commands:

• luksFormat: Formats a device with a new LUKS header and sets an initial passphrase. This is the first step to create an encrypted volume.
• open <device> [<name>]: Opens an encrypted device (LUKS or plain) and maps it to a decrypted device-mapper name (e.g., /dev/mapper/<name>). This decrypted device can then be used for filesystem creation and mounting.
• close <name>: Closes an opened encrypted device, removing its mapping from /dev/mapper.
• luksAddKey: Adds a new passphrase or key to a LUKS volume.
• luksRemoveKey: Removes an existing passphrase or key from a LUKS volume.
• luksDump: Displays information about the LUKS header, including key slots, UUID, and encryption parameters.
• luksHeaderBackup: Backs up the LUKS header to a file. Crucial for recovery in case of header corruption.

The LUKS header contains all critical metadata for accessing the encrypted data, including encryption parameters (cipher, key size, hash), key slot information, and encrypted master keys. Without a valid and intact LUKS header, the data on the encrypted volume is irrecoverable. Regular backups of the LUKS header are highly recommended using luksHeaderBackup to protect against accidental corruption or deletion.

The security of a LUKS volume heavily relies on the strength of its passphrases and the parameters used for the Password-Based Key Derivation Function (PBKDF). cryptsetup allows configuration of PBKDF parameters like iter-time (iterations), pbkdf-memory-cost (memory usage, especially for Argon2), and pbkdf-parallel-threads. Modern cryptsetup versions default to Argon2, which is more resistant to brute-force attacks than older PBKDF2 due to its memory-hard and time-hard properties. Users should choose strong, unique passphrases and ensure PBKDF parameters are adequately configured for their security needs.

cryptsetup originated as a user-friendly front-end to the dm-crypt kernel module, which provides transparent encryption of block devices. The dm-crypt project itself was created in 2002. cryptsetup was developed to simplify the often complex setup and management of dm-crypt volumes. A significant milestone was the adoption and robust support for the LUKS (Linux Unified Key Setup) standard, developed in 2004 by Clemens Fruhwirth. LUKS provided a standardized on-disk format for encrypted volumes, enabling multi-user key management, key revocation, and improved interoperability across Linux distributions. This standardization greatly enhanced the usability and security of encrypted volumes, making cryptsetup and LUKS the de-facto standard for disk encryption on Linux.

dmsetup(8), lsblk(8), fdisk(8), parted(8), mount(8), mkfs(8), dd(1)