📛 NAME
cryptsetup — manage plain dm-crypt and LUKS encrypted volumes
🚀 Quick Reference
| Use Case | Command | Description |
|---|
| 📦 Create LUKS2 container | cryptsetup --type luks2 luksFormat /dev/sdX | Initialize a LUKS2 partition with passphrase |
| 🔓 Open LUKS container | cryptsetup open /dev/sdX sdX_crypt | Map LUKS device to /dev/mapper/sdX_crypt |
| 🔒 Close mapping | cryptsetup close sdX_crypt | Remove mapping and wipe key from kernel |
| ➕ Add passphrase | cryptsetup luksAddKey /dev/sdX | Add a new passphrase to a key slot |
| ➖ Remove passphrase | cryptsetup luksRemoveKey /dev/sdX | Remove a passphrase (interactive or via file) |
| 🔄 Change passphrase | cryptsetup luksChangeKey /dev/sdX | Change an existing passphrase |
| 📊 Status | cryptsetup status sdX_crypt | Show mapping status and cipher info |
| 📏 Resize | cryptsetup resize sdX_crypt | Resize active mapping to underlying device size |
| 📄 Dump header | cryptsetup luksDump /dev/sdX | Display LUKS header information |
| 💾 Backup header | cryptsetup luksHeaderBackup /dev/sdX --header-backup-file file | Save binary backup of header and keyslots |
| 📥 Restore header | cryptsetup luksHeaderRestore /dev/sdX --header-backup-file file | Restore header from backup file |
| 🗑️ Erase keyslots | cryptsetup erase /dev/sdX | Wipe all keyslots, making container permanently inaccessible |
| ⏸️ Suspend | cryptsetup luksSuspend sdX_crypt | Suspend device, wipe key, block I/O |
| ▶️ Resume | cryptsetup luksResume sdX_crypt | Resume suspended device |
| ⚡ Benchmark | cryptsetup benchmark | Benchmark ciphers and KDF (memory‑only) |
📋 SYNOPSIS
cryptsetup <options> <action> <action args>
📖 DESCRIPTION
cryptsetup is used to conveniently setup dm-crypt managed device-mapper mappings. These include plain dm-crypt volumes and LUKS volumes. The difference is that LUKS uses a metadata header and can hence offer more features than plain dm-crypt. On the other hand, the header is visible and vulnerable to damage.
In addition, cryptsetup provides limited support for the use of loop-AES volumes, TrueCrypt, VeraCrypt and BitLocker compatible volumes.
🔍 PLAIN DM-CRYPT OR LUKS?
Unless you understand the cryptographic background well, use LUKS. With plain dm-crypt there are a number of possible user errors that massively decrease security. While LUKS cannot fix them all, it can lessen the impact for many of them.
⚠️ WARNINGS
A lot of good information on the risks of using encrypted storage, on handling problems and on security aspects can be found in the Cryptsetup FAQ. Read it. Nonetheless, some risks deserve to be mentioned here.
- 💾 Backup: Storage media die. Encryption has no influence on that. Backup is mandatory for encrypted data as well, if the data has any worth. See the Cryptsetup FAQ for advice on how to do a backup of an encrypted volume.
- 🔤 Character encoding: If you enter a passphrase with special symbols, the passphrase can change depending on character encoding. Keyboard settings can also change, which can make blind input hard or impossible. For example, switching from some ASCII 8-bit variant to UTF-8 can lead to a different binary encoding and hence different passphrase seen by cryptsetup, even if what you see on the terminal is exactly the same. It is therefore highly recommended to select passphrase characters only from 7-bit ASCII, as the encoding for 7-bit ASCII stays the same for all ASCII variants and UTF-8.
- 📄 LUKS header: If the header of a LUKS volume gets damaged, all data is permanently lost unless you have a header-backup. If a key-slot is damaged, it can only be restored from a header-backup or if another active key-slot with known passphrase is undamaged. Damaging the LUKS header is something people manage to do with surprising frequency. This risk is the result of a trade-off between security and safety, as LUKS is designed for fast and secure wiping by just overwriting header and key-slot area.
- 🗑️ Previously used partitions: If a partition was previously used, it is a very good idea to wipe filesystem signatures, data, etc. before creating a LUKS or plain dm-crypt container on it. For a quick removal of filesystem signatures, use "wipefs". Take care though that this may not remove everything. In particular, MD RAID signatures at the end of a device may survive. It also does not remove data. For a full wipe, overwrite the whole partition before container creation. If you do not know how to do that, the cryptsetup FAQ describes several options.
🔧 BASIC ACTIONS
The following are valid actions for all supported device types.
- open <device> <name> --type <device_type> — Opens (creates a mapping with) <name> backed by device <device>. Device type can be plain, luks (default), luks1, luks2, loopaes or tcrypt. For backward compatibility there are open command aliases: create (argument-order <name> <device>): open --type plain; plainOpen: open --type plain; luksOpen: open --type luks; loopaesOpen: open --type loopaes; tcryptOpen: open --type tcrypt; bitlkOpen: open --type bitlk. <options> are type specific.
- close <name> — Removes the existing mapping <name> and wipes the key from kernel memory. Aliases: remove, plainClose, luksClose, loopaesClose, tcryptClose. Options: [--deferred] or [--cancel-deferred].
- status <name> — Reports the status for the mapping <name>.
- resize <name> — Resizes an active mapping. If --size or --device-size not specified, size computed from underlying device. For LUKS it is device size minus LUKS header area. For plain crypt, whole device size is used. Options for LUKS2: [--token-id, --token-only, --token-type, --key-slot, --key-file, --keyfile-size, --keyfile-offset, --timeout, --disable-external-tokens, --disable-locks, --disable-keyring].
- refresh <name> — Refreshes parameters of active mapping without deactivating device. Supports LUKS1, LUKS2 (including authenticated encryption), plain crypt and loopaes. May change --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue and --allow-discards. For LUKS2: --integrity-no-journal, --persistent, --disable-keyring.
- reencrypt <device> or --active-name <name> [<new_name>] — Run resilient reencryption (LUKS2 only). Modes: device reencryption (reencrypt), device encryption (reencrypt --encrypt), device decryption (reencrypt --decrypt). May be interrupted with SIGTERM and resumed. Options: [--encrypt, --decrypt, --device-size, --resilience, --resilience-hash, --hotzone-size, --init-only, --resume-only, --reduce-device-size, --master-key-file, --key-size].
🔓 PLAIN MODE
Plain dm-crypt encrypts the device sector-by-sector with a single, non-salted hash of the passphrase. No checks, no metadata. Mapped devices usually reside in /dev/mapper/<name>.
🔐 LUKS EXTENSION
LUKS, the Linux Unified Key Setup, is a standard for disk encryption. It adds a standardized header, key-slot area, and bulk data area. LUKS2 is a new format with additional extensions. Each passphrase is associated with one of up to 8 key-slots (LUKS1) or 32 (LUKS2).
- luksFormat <device> [<key file>] — Initializes a LUKS partition and sets initial passphrase (key-slot 0). Options: [--hash, --cipher, --verify-passphrase, --key-size, --key-slot, --key-file, --keyfile-offset, --keyfile-size, --use-random | --use-urandom, --uuid, --master-key-file, --iter-time, --header, --pbkdf-force-iterations, --force-password, --disable-locks]. For LUKS2 additional: [--integrity, --integrity-no-wipe, --sector-size, --label, --subsystem, --pbkdf, --pbkdf-memory, --pbkdf-parallel, --disable-locks, --disable-keyring, --luks2-metadata-size, --luks2-keyslots-size, --keyslot-cipher, --keyslot-key-size]. WARNING: Doing a luksFormat on an existing LUKS container will make all data permanently irretrievable unless you have a header backup.
- open --type luks <device> <name> or luksOpen <device> <name> (old syntax) — Opens LUKS device after successful passphrase verification. First searches LUKS tokens, then prompts. Options: [--key-file, --keyfile-offset, --keyfile-size, --readonly, --test-passphrase, --allow-discards, --header, --key-slot, --master-key-file, --token-id, --token-only, --token-type, --disable-external-tokens, --disable-keyring, --disable-locks, --type, --refresh, --serialize-memory-hard-pbkdf].
- luksSuspend <name> — Suspends an active device (I/O blocks) and wipes encryption key from kernel memory. Needs kernel 2.6.19+. Use luksResume to reinstate key. Options: [--header, --disable-locks].
- luksResume <name> — Resumes a suspended device and reinstates the encryption key. Options: [--key-file, --keyfile-size, --header, --disable-keyring, --disable-locks, --type].
- luksAddKey <device> [<key file with new key>] — Adds a new passphrase. Requires an existing passphrase. With --unbound creates unbound LUKS2 keyslot. Options: [--key-file, --keyfile-offset, --keyfile-size, --new-keyfile-offset, --new-keyfile-size, --key-slot, --master-key-file, --force-password, --header, --disable-locks, --iter-time, --pbkdf, --pbkdf-force-iterations, --unbound, --type, --keyslot-cipher, --keyslot-key-size].
- luksRemoveKey <device> [<key file with passphrase to be removed>] — Removes the supplied passphrase. Options: [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type]. WARNING: Removing the last passphrase makes the container permanently inaccessible.
- luksChangeKey <device> [<new key file>] — Changes an existing passphrase. Options: [--key-file, --keyfile-offset, --keyfile-size, --new-keyfile-offset, --iter-time, --pbkdf, --pbkdf-force-iterations, --new-keyfile-size, --key-slot, --force-password, --header, --disable-locks, --type, --keyslot-cipher, --keyslot-key-size].
- luksConvertKey <device> — Converts an existing LUKS2 keyslot to new pbkdf parameters. Options: [--key-file, --keyfile-offset, --keyfile-size, --key-slot, --header, --disable-locks, --iter-time, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --keyslot-cipher, --keyslot-key-size].
- luksKillSlot <device> <key slot number> — Wipes a specific key-slot. Requires a remaining passphrase unless batch-mode. Options: [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type].
- erase <device> or luksErase <device> — Erases all keyslots, making the LUKS container permanently inaccessible. No password needed.
- luksUUID <device> — Print UUID of a LUKS device. Set new UUID if --uuid option specified.
- isLuks <device> — Returns true if device is a LUKS device. Use -v for human-readable feedback. Use --type for specific version.
- luksDump <device> — Dump header information. With --dump-master-key dumps the master key. With --dump-json-metadata dumps LUKS2 JSON metadata. Options: [--dump-master-key, --dump-json-metadata, --key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --master-key-file, --type, --unbound, --key-slot].
- luksHeaderBackup <device> --header-backup-file <file> — Stores a binary backup of LUKS header and keyslot area.
- luksHeaderRestore <device> --header-backup-file <file> — Restores a binary backup. Requires matching master key size and data offset.
- token <add|remove|import|export> <device> — Manage LUKS2 tokens. Options: [--header, --token-id, --key-slot, --key-description, --disable-external-tokens, --disable-locks, --disable-keyring, --json-file].
- convert <device> --type <format> — Convert between LUKS1 and LUKS2 format. Must be performed on inactive device. Options: [--header, --type].
- config <device> — Set permanent configuration options (LUKS2 only). Options: [--priority, --label, --subsystem, --key-slot, --header].
🔗 loop-AES EXTENSION
- open --type loopaes <device> <name> --key-file <keyfile> — Opens loop-AES encrypted partition. Use --keyfile-size for key length, --offset for device offset, --skip for IV offset, --hash to override hash function. Options: [--key-file, --key-size, --offset, --skip, --hash, --readonly, --allow-discards, --refresh].
🔐 TCRYPT (TrueCrypt-compatible and VeraCrypt) EXTENSION
Supports mapping TrueCrypt, tcplay or VeraCrypt encrypted partitions. Header formatting not supported. Requires kernel userspace crypto API. Options for open: [--key-file, --tcrypt-hidden, --tcrypt-system, --tcrypt-backup, --readonly, --test-passphrase, --allow-discards, --disable-veracrypt, --veracrypt-pim, --veracrypt-query-pim, --header, --cipher, --hash].
- open --type tcrypt <device> <name> — Opens TCRYPT device.
- tcryptDump <device> — Dump header information. Options: [--dump-master-key, --key-file, --tcrypt-hidden, --tcrypt-system, --tcrypt-backup, --cipher, --hash].
🪟 BITLK (Windows BitLocker-compatible) EXTENSION (EXPERIMENTAL)
Supports mapping BitLocker encrypted partitions. Header formatting not supported. Requires kernel userspace crypto API. For unlocking need password, recovery passphrase, startup key, or master key (FVEK).
- open --type bitlk <device> <name> — Options: [--key-file, --readonly, --test-passphrase, --allow-discards, --master-key-file].
- bitlkDump <device> — Options: [--dump-master-key, --master-key-file].
🛠️ MISCELLANEOUS
- repair <device> — Tries to repair LUKS metadata. Useful for fixing benign corruptions. Also repairs LUKS2 reencryption metadata. Options: --type.
- benchmark <options> — Benchmarks ciphers and KDF. Without parameters measures common configurations. Use --cipher and --key-size for cipher test, --hash for KDF test. Requires kernel userspace crypto API.
⚙️ OPTIONS
- --verbose, -v — Print more information on command execution.
- --debug or --debug-json — Run in debug mode with full diagnostic logs. Debug output lines prefixed by '#'.
- --type <device-type> — Specifies required device type.
- --hash, -h <hash-spec> — Specifies passphrase hash for plain/loopaes open, or hash for LUKS key setup. Minimum 160 bits output for LUKS.
- --cipher, -c <cipher-spec> — Set cipher specification string. Default for plain: "aes-cbc-essiv:sha256"; for LUKS: "aes-xts-plain64".
- --verify-passphrase, -y — Ask for passphrase twice when interactively prompted.
- --key-file, -d name — Read passphrase from file. "-" reads from stdin.
- --keyfile-offset value — Skip bytes at beginning of key file.
- --keyfile-size, -l value — Read maximum bytes from key file.
- --new-keyfile-offset value — Skip bytes when adding new passphrase from key file.
- --new-keyfile-size value — Read maximum bytes when adding new passphrase.
- --master-key-file — Use a master key stored in a file.
- --dump-json-metadata — For luksDump (LUKS2) prints JSON metadata area.
- --dump-master-key — Include master key in luksDump output.
- --json-file — Read/write token JSON from/to file.
- --use-random / --use-urandom — Choose kernel RNG for master key creation.
- --key-slot, -S <0-N> — Specify key slot for LUKS operations.
- --key-size, -s <bits> — Set key size in bits.
- --size, -b <number of 512 byte sectors> — Set device size in sectors.
- --offset, -o <number of 512 byte sectors> — Start offset in backend device.
- --skip, -p <number of 512 byte sectors> — Start offset for IV calculation.
- --device-size size[units] — Use specified size instead of real device size.
- --readonly, -r — Set up read-only mapping.
- --shared — Create additional mapping for common ciphertext device (plain only).
- --pbkdf <PBKDF spec> — Set PBKDF algorithm: pbkdf2, argon2i, argon2id.
- --iter-time, -i <number of milliseconds> — Time to spend with PBKDF passphrase processing.
- --pbkdf-memory <number> — Memory cost for PBKDF (Argon2 only, in KB).
- --pbkdf-parallel <number> — Parallel cost for PBKDF (threads, up to 4).
- --pbkdf-force-iterations <num> — Set iterations directly, bypass benchmark.
- --batch-mode, -q — Suppress confirmation questions.
- --progress-frequency <seconds> — Print wipe progress every <seconds>.
- --timeout, -t <number of seconds> — Timeout for passphrase input.
- --tries, -T — Number of passphrase retries (default 3).
- --align-payload <number of 512 byte sectors> — DEPRECATED. Align payload at boundary.
- --uuid=UUID — Use provided UUID for luksFormat or change existing UUID.
- --allow-discards — Allow discard (TRIM) requests. Security risk: may leak filesystem info.
- --perf-same_cpu_crypt — Perform encryption on same CPU as IO submission.
- --perf-submit_from_crypt_cpus — Disable offloading writes to separate thread.
- --perf-no_read_workqueue, --perf-no_write_workqueue — Bypass dm-crypt internal workqueue.
- --test-passphrase — Verify passphrase without activating device.
- --header <device or file> — Use detached LUKS header.
- --header-backup-file <file> — Specify file for header backup/restore.
- --force-password — Skip password quality checking.
- --deferred — Defer device removal until last user closes.
- --cancel-deferred — Cancel previously configured deferred removal.
- --disable-external-tokens — Disable plugins for external LUKS2 tokens.
- --disable-locks — Disable lock protection for metadata.
- --disable-keyring — Do not load volume key in kernel keyring.
- --key-description <text> — Set key description in keyring.
- --priority <normal|prefer|ignore> — Set keyslot priority for LUKS2.
- --token-id — Specify token to use.
- --token-only — Fail if token activation fails.
- --token-type — Restrict tokens to specific type.
- --sector-size <bytes> — Set sector size (512-4096, power of 2).
- --iv-large-sectors — Count IV in larger sector size (plain only).
- --persistent — Store activation flags persistently in LUKS2 metadata.
- --refresh — Refresh active device parameters.
- --label <LABEL> — Set label for LUKS2 device.
- --subsystem <SUBSYSTEM> — Set subsystem description for LUKS2 device.
- --integrity <integrity algorithm> — Specify integrity algorithm for authenticated encryption (EXPERIMENTAL).
- --luks2-metadata-size <size> — Enlarge LUKS2 metadata area.
- --luks2-keyslots-size <size> — Set size of LUKS2 binary keyslot area.
- --keyslot-cipher <cipher-spec> — Set cipher for LUKS2 keyslot area.
- --keyslot-key-size <bits> — Set key size for LUKS2 keyslot area.
- --integrity-no-journal — Activate integrity device without data journal.
- --integrity-no-wipe — Skip wiping of authentication tags.
- --unbound — Create or dump LUKS2 unbound keyslot.
- --tcrypt-hidden — Use hidden TrueCrypt header.
- --tcrypt-system — Use system encryption header.
- --tcrypt-backup — Use backup header.
- --disable-veracrypt — Disable VeraCrypt support.
- --veracrypt-pim — Specify custom PIM value.
- --veracrypt-query-pim — Prompt for PIM value.
- --serialize-memory-hard-pbkdf — Use global lock for memory-hard PBKDF.
- --encrypt — Initialize device encryption.
- --decrypt — Initialize device decryption.
- --init-only — Initialize reencryption in metadata only.
- --resume-only — Resume reencryption only.
- --resilience <mode> — Reencryption resilience mode: checksum, journal, none.
- --resilience-hash <hash> — Hash algorithm for checksum resilience.
- --hotzone-size <size> — Upper limit on reencryption hotzone size.
- --reduce-device-size <size> — Reduce device size during reencryption encryption.
- --version — Show program version.
- --usage — Show short option help.
- --help, -? — Show help text and default parameters.
💡 EXAMPLE
- Create LUKS2 container on block device /dev/sdX:
sudo cryptsetup --type luks2 luksFormat /dev/sdX
- Add an additional passphrase to key slot 5:
sudo cryptsetup luksAddKey --key-slot 5 /dev/sdX
- Create LUKS header backup and save it to file:
sudo cryptsetup luksHeaderBackup /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile
- Open LUKS container on /dev/sdX and map it to sdX_crypt:
sudo cryptsetup open /dev/sdX sdX_crypt
- WARNING: The command in example 5 will erase all key slots. You cannot use your luks container afterwards anymore unless you have a backup to restore.
sudo cryptsetup erase /dev/sdX
- Restore LUKS header from backup file:
sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile
🚪 Exit Codes
Cryptsetup returns 0 on success and a non-zero value on error.
- 1 — wrong parameters
- 2 — no permission (bad passphrase)
- 3 — out of memory
- 4 — wrong device specified
- 5 — device already exists or device is busy
📝 NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE
No iterated hashing or salting in plain mode. Direct hash only.
- From a terminal: Passphrase read until first newline, then hashed and truncated to key size.
- From stdin: Read until newline (or max input size), trailing newline stripped. Hashed with default hash. If --hash is "plain", input used directly as binary key.
- From a key file: Truncated to key size and used directly as binary key. --hash ignored.
📝 NOTES ON PASSPHRASE PROCESSING FOR LUKS
Uses PBKDF2 to protect against dictionary attacks.
- From a terminal: Passphrase read until first newline, then processed by PBKDF2.
- From stdin: Read up to first newline or compiled-in maximum key file length. --keyfile-size ignored.
- From key file: Complete file read up to compiled-in maximum. Newlines do not terminate. --keyfile-size can limit.
- Passphrase processing: For luksAddKey/luksFormat, --iter-time determines PBKDF2 iteration count. Default 1-2 seconds sufficient for most cases.
⚠️ INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS
LUKS checks for valid passphrase; plain dm-crypt decrypts always, leaving data encrypted if wrong key given.
🔬 NOTES ON SUPPORTED CIPHERS, MODES, HASHES AND KEY SIZES
Depends on kernel support. See /proc/crypto. For libgcrypt backend, all gcrypt algorithms available.
🔑 NOTES ON PASSPHRASES
Keep passphrases safe. Use LUKS for multiple passphrases as fallback.
🎲 NOTES ON RANDOM NUMBER GENERATORS
Always kernel RNGs. /dev/urandom used for salts, AF splitter, and wiping. Master key can use /dev/random or /dev/urandom via --use-random/--use-urandom. Low-entropy systems may have issues.
🔒 AUTHENTICATED DISK ENCRYPTION (EXPERIMENTAL)
Requires Linux kernel 4.12+ with dm-integrity and AEAD algorithms. Provides confidentiality and integrity. Uses dm-integrity for per-sector metadata and journal. Available space reduced. Use --integrity option in luksFormat. Does not support discards. All modes experimental.
💿 NOTES ON LOOPBACK DEVICE USE
If device argument is a file, cryptsetup allocates a loopback device. Requires kernel 2.6.25+ with autoclear flag. See losetup(8).
🔒 LUKS2 header locking
LUKS2 uses locking mechanism for atomic updates. For file images uses flock(2); for block devices uses lock file in /run/lock/cryptsetup. Only LUKS2 uses locks.
🗑️ DEPRECATED ACTIONS
reload removed; use dmsetup(8). luksDelKey replaced with luksKillSlot.
🐛 REPORTING BUGS
Report bugs on cryptsetup mailing list at dm-crypt AT saout.de or in 'Issues' section on LUKS website. Attach output with --debug.
👤 AUTHORS
cryptsetup originally written by Jana Saout <jana AT saout.de>. LUKS extensions and original man page by Clemens Fruhwirth <clemens@endorphin.org>. Man page extensions by Milan Broz <gmazyland AT gmail.com>. Man page rewrite and extension by Arno Wagner <arno AT wagner.name>.
©️ COPYRIGHT
Copyright © 2004 Jana Saout, Copyright © 2004-2006 Clemens Fruhwirth, Copyright © 2012-2014 Arno Wagner, Copyright © 2009-2021 Red Hat, Inc., Copyright © 2009-2021 Milan Broz. This is free software; see source for copying conditions. NO WARRANTY.
📚 SEE ALSO
