cryptsetup-open

Open a LUKS volume and create a decrypted mapping at /dev/mapper/mapping_name

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

$ cryptsetup open [[-k|--key-file]] [path/to/file] [/dev/sdXY] [mapping_name]

$ cryptsetup open --allow-discards [/dev/sdXY] [mapping_name]

$ cryptsetup open --allow-discards --persistent [/dev/sdXY] [mapping_name]

$ cryptsetup open [[-r|--readonly]] [/dev/sdXY] [mapping_name]

cryptsetup open <device> <name> [options]
or (for LUKS devices)
cryptsetup luksOpen <device> <name> [options]

<device>
    The path to the encrypted block device (e.g., /dev/sda1 or /dev/disk/by-uuid/...).

<name>
    The desired name for the decrypted device-mapper mapping (e.g., myvolume would create /dev/mapper/myvolume).

--type <TYPE>
    Specifies the device type. Common types include luks (default for luksOpen), plain, or loopaes.

--key-file <FILE>
    Uses a specified key file for decryption instead of prompting for a passphrase. The key file's permissions must be secure.

--key-slot <NUM>
    Specifies which key slot (0-7 for LUKS1, 0-31 for LUKS2) to use for decryption. If not specified, all active key slots are tried.

--header <FILE>
    Uses an external header file for LUKS metadata instead of the one on the device. Useful for damaged devices or backups.

--read-only
    Opens the device in read-only mode, preventing any writes to the decrypted volume.

--allow-discards
    Enables TRIM/discard support for SSDs or virtual machines, allowing the underlying device to reclaim unused blocks. This can have security implications if not understood.

--uuid <UUID>
    Specifies the UUID of the LUKS device to open, useful when device paths are not stable.

--persistent
    Creates a persistent device-mapper mapping that can be handled by systemd-cryptsetup-generator for automatic opening during boot.

The command cryptsetup open is used to decrypt an encrypted block device (typically formatted with LUKS - Linux Unified Key Setup) and make its contents accessible to the operating system. When successful, it creates a new virtual block device under /dev/mapper/ (e.g., /dev/mapper/myencryptedvolume) which represents the decrypted data. This decrypted device can then be mounted like any regular block device (e.g., using mount command) to access the underlying filesystem.

The open action requires a passphrase or a key file to decrypt the device. It utilizes the Linux kernel's device-mapper subsystem to perform the encryption/decryption on-the-fly, providing a transparent layer for data access. It's a fundamental command for managing encrypted storage in Linux environments.

Important Caveats:
• Requires root privileges to execute.
• An incorrect passphrase or key file will result in a failure to open the device.
• If the target device name (<name>) is already in use under /dev/mapper/, the command will fail.
• Improperly closing (not running cryptsetup close) or forcefully unmounting the underlying filesystem can lead to data corruption. Always unmount the filesystem before closing the device.
• Using --key-file requires careful attention to the security of the key file itself, as its compromise directly leads to data exposure.
• Enabling --allow-discards can potentially leak information about file deletions or free space, as it exposes block usage patterns to the underlying storage.

The typical workflow for accessing an encrypted LUKS volume involves three steps:
1. Open the encrypted device: cryptsetup open <device> <name>
2. Mount the decrypted filesystem: mount /dev/mapper/<name> /mnt/mountpoint
3. When finished, unmount the filesystem: umount /mnt/mountpoint
4. Close the encrypted device: cryptsetup close <name>
It is crucial to unmount the filesystem before closing the device to prevent data loss or corruption.

cryptsetup open does not directly access the filesystem on the encrypted device. Instead, it interacts with the Linux kernel's device-mapper subsystem. This subsystem creates a new virtual block device (/dev/mapper/<name>) that acts as a transparent layer. All I/O operations to this virtual device are intercepted by dm-crypt, decrypted or encrypted on-the-fly, and then passed to the underlying physical device. This design ensures that applications and the kernel's filesystem drivers interact only with unencrypted data, simplifying the encryption process from their perspective.

The cryptsetup utility and its open action are integral parts of the Linux disk encryption landscape, primarily driven by the dm-crypt kernel module and the LUKS (Linux Unified Key Setup) on-disk format.

The dm-crypt module, which provides transparent device encryption, was merged into the Linux kernel around 2004. cryptsetup emerged as the user-space tool to manage dm-crypt devices, significantly simplifying its usage compared to direct dmsetup commands. The LUKS specification, developed by Clemens Fruhwirth, standardized the on-disk format for dm-crypt, allowing for multi-passphrase support and easier portability of encrypted volumes across different Linux systems. cryptsetup became the primary tool for creating and managing LUKS volumes.

Over the years, cryptsetup has seen continuous development, incorporating features like LUKS2 (with support for more key slots, different PBKDFs, and JSON metadata), TRIM/discard support, and tighter integration with system boot processes (e.g., via initramfs and systemd-cryptsetup) to facilitate seamless unlocking of root filesystems or other critical encrypted partitions during startup.

cryptsetup(8), crypttab(5), mount(8), umount(8), dmsetup(8), fstab(5)