---

   cryptsetup    ( 8 )

---

LUKS EXTENSION

LUKS, the Linux Unified Key Setup, is a standard for disk encryption. It adds a standardized header at the start of the device, a key-slot area directly behind the header and the bulk data area behind that. The whole set is called a 'LUKS container'. The device that a LUKS container resides on is called a 'LUKS device'. For most purposes, both terms can be used interchangeably. But note that when the LUKS header is at a nonzero offset in a device, then the device is not a LUKS device anymore, but has a LUKS container stored in it at an offset.

LUKS can manage multiple passphrases that can be individually revoked or changed and that can be securely scrubbed from persistent media due to the use of anti-forensic stripes. Passphrases are protected against brute-force and dictionary attacks by PBKDF2, which implements hash iteration and salting in one function.

LUKS2 is a new version of header format that allows additional extensions like different PBKDF algorithm or authenticated encryption. You can format device with LUKS2 header if you specify --type luks2 in luksFormat command. For activation, the format is already recognized automatically.

Each passphrase, also called a key in this document, is associated with one of 8 key-slots. Key operations that do not specify a slot affect the first slot that matches the supplied passphrase or the first empty slot if a new passphrase is added.

The <device> parameter can also be specified by a LUKS UUID in the format UUID=<uuid>. Translation to real device name uses symlinks in /dev/disk/by-uuid directory.

To specify a detached header, the --header parameter can be used in all LUKS commands and always takes precedence over the positional <device> parameter.

The following are valid LUKS actions:

luksFormat <device> [<key file>]

Initializes a LUKS partition and sets the initial passphrase (for key-slot 0), either via prompting or via <key file>. Note that if the second argument is present, then the passphrase is taken from the file given there, without the need to use the --key-file option. Also note that for both forms of reading the passphrase from a file you can give '-' as file name, which results in the passphrase being read from stdin and the safety-question being skipped.

You cannot call luksFormat on a device or filesystem that is mapped or in use, e.g. mounted filesysem, used in LVM, active RAID member etc. The device or filesystem has to be un-mounted in order to call luksFormat.

To use LUKS2, specify --type luks2.

<options> can be [--hash, --cipher, --verify-passphrase, --key-size, --key-slot, --key-file (takes precedence over optional second argument), --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 <options> can be [--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 the old container permanently irretrievable unless you have a header backup.

open --type luks <device> <name> luksOpen <device> <name> (old syntax)

Opens the LUKS device <device> and sets up a mapping <name> after successful verification of the supplied passphrase.

First, the passphrase is searched in LUKS tokens. If it's not found in any token and also the passphrase is not supplied via --key-file, the command prompts for it interactively.

<options> can be [--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 (all IO operations will block and accesses to the device will wait indefinitely) and wipes the encryption key from kernel memory. Needs kernel 2.6.19 or later.

After this operation you have to use luksResume to reinstate the encryption key and unblock the device or close to remove the mapped device.

WARNING: never suspend the device on which the cryptsetup binary resides.

<options> can be [--header, --disable-locks].

luksResume <name>

Resumes a suspended device and reinstates the encryption key. Prompts interactively for a passphrase if --key-file is not given.

<options> can be [--key-file, --keyfile-size, --header, --disable-keyring, --disable-locks, --type]

luksAddKey <device> [<key file with new key>]

Adds a new passphrase. An existing passphrase must be supplied interactively or via --key-file. The new passphrase to be added can be specified interactively or read from the file given as positional argument.

NOTE: with --unbound option the action creates new unbound LUKS2 keyslot. The keyslot cannot be used for device activation. If you don't pass new key via --master-key-file option, new random key is generated. Existing passphrase for any active keyslot is not required.

<options> can be [--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 from the LUKS device. The passphrase to be removed can be specified interactively, as the positional argument or via --key-file.

<options> can be [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type]

WARNING: If you read the passphrase from stdin (without further argument or with '-' as an argument to --key-file), batch-mode (-q) will be implicitly switched on and no warning will be given when you remove the last remaining passphrase from a LUKS container. Removing the last passphrase makes the LUKS container permanently inaccessible.

luksChangeKey <device> [<new key file>]

Changes an existing passphrase. The passphrase to be changed must be supplied interactively or via --key-file. The new passphrase can be supplied interactively or in a file given as positional argument.

If a key-slot is specified (via --key-slot), the passphrase for that key-slot must be given and the new passphrase will overwrite the specified key-slot. If no key-slot is specified and there is still a free key-slot, then the new passphrase will be put into a free key-slot before the key-slot containing the old passphrase is purged. If there is no free key-slot, then the key-slot with the old passphrase is overwritten directly.

WARNING: If a key-slot is overwritten, a media failure during this operation can cause the overwrite to fail after the old passphrase has been wiped and make the LUKS container inaccessible.

<options> can be [--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. The passphrase for keyslot to be converted must be supplied interactively or via --key-file. If no --pbkdf parameters are specified LUKS2 default pbkdf values will apply.

If a keyslot is specified (via --key-slot), the passphrase for that keyslot must be given. If no keyslot is specified and there is still a free keyslot, then the new parameters will be put into a free keyslot before the keyslot containing the old parameters is purged. If there is no free keyslot, then the keyslot with the old parameters is overwritten directly.

WARNING: If a keyslot is overwritten, a media failure during this operation can cause the overwrite to fail after the old parameters have been wiped and make the LUKS container inaccessible.

<options> can be [--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>

Wipe the key-slot number <key slot> from the LUKS device. Except running in batch-mode (-q) a remaining passphrase must be supplied, either interactively or via --key-file. This command can remove the last remaining key-slot, but requires an interactive confirmation when doing so. Removing the last passphrase makes a LUKS container permanently inaccessible.

<options> can be [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type].

WARNING: If you read the passphrase from stdin (without further argument or with '-' as an argument to --key- file), batch-mode (-q) will be implicitly switched on and no warning will be given when you remove the last remaining passphrase from a LUKS container. Removing the last passphrase makes the LUKS container permanently inaccessible.

NOTE: If there is no passphrase provided (on stdin or through --key-file argument) and batch-mode (-q) is active, the key-slot is removed without any other warning.

erase <device> luksErase <device>

Erase all keyslots and make the LUKS container permanently inaccessible. You do not need to provide any password for this operation.

WARNING: This operation is irreversible.

luksUUID <device>

Print the UUID of a LUKS device. Set new UUID if --uuid option is specified.

isLuks <device>

Returns true, if <device> is a LUKS device, false otherwise. Use option -v to get human-readable feedback. 'Command successful.' means the device is a LUKS device.

By specifying --type you may query for specific LUKS version.

luksDump <device>

Dump the header information of a LUKS device.

If the --dump-master-key option is used, the LUKS device master key is dumped instead of the keyslot info. Together with --master-key-file option, master key is dumped to a file instead of standard output. Beware that the master key cannot be changed without reencryption and can be used to decrypt the data stored in the LUKS container without a passphrase and even without the LUKS header. This means that if the master key is compromised, the whole device has to be erased or reencrypted to prevent further access. Use this option carefully.

To dump the master key, a passphrase has to be supplied, either interactively or via --key-file.

To dump unbound key (LUKS2 format only), --unbound parameter, specific --key-slot id and proper passphrase has to be supplied, either interactively or via --key-file. Optional --master-key-file parameter enables unbound keyslot dump to a file.

To dump LUKS2 JSON metadata (without basic heade information like UUID) use --dump-json-metadata option.

<options> can be [--dump-master-key, --dump-json-metadata, --key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --master-key-file, --type, --unbound, --key-slot].

WARNING: If --dump-master-key is used with --key-file and the argument to --key-file is '-', no validation question will be asked and no warning given.

luksHeaderBackup <device> --header-backup-file <file>

Stores a binary backup of the LUKS header and keyslot area. Note: Using '-' as filename writes the header backup to a file named '-'.

WARNING: This backup file and a passphrase valid at the time of backup allows decryption of the LUKS data area, even if the passphrase was later changed or removed from the LUKS device. Also note that with a header backup you lose the ability to securely wipe the LUKS device by just overwriting the header and key-slots. You either need to securely erase all header backups in addition or overwrite the encrypted data area as well. The second option is less secure, as some sectors can survive, e.g. due to defect management.

luksHeaderRestore <device> --header-backup-file <file>

Restores a binary backup of the LUKS header and keyslot area from the specified file. Note: Using '-' as filename reads the header backup from a file named '-'.

WARNING: Header and keyslots will be replaced, only the passphrases from the backup will work afterward.

This command requires that the master key size and data offset of the LUKS header already on the device and of the header backup match. Alternatively, if there is no LUKS header on the device, the backup will also be written to it.

token <add|remove|import|export> <device>

Action add creates new keyring token to enable auto- activation of the device. For the auto-activation, the passphrase must be stored in keyring with the specified description. Usually, the passphrase should be stored in user or user-session keyring. The token command is supported only for LUKS2.

For adding new keyring token, option --key-description is mandatory. Also, new token is assigned to key slot specified with --key-slot option or to all active key slots in the case --key-slot option is omitted.

To remove existing token, specify the token ID which should be removed with --token-id option.

WARNING: The action token remove removes any token type, not just keyring type from token slot specified by --token-id option.

Action import can store arbitrary valid token json in LUKS2 header. It may be passed via standard input or via file passed in --json-file option. If you specify --key-slot then successfully imported token is also assigned to the key slot.

Action export writes requested token json to a file passed with --json-file or to standard output.

<options> can be [--header, --token-id, --key-slot, --key-description, --disable-external-tokens, --disable-locks, --disable-keyring, --json-file].

convert <device> --type <format>

Converts the device between LUKS1 and LUKS2 format (if possible). The conversion will not be performed if there is an additional LUKS2 feature or LUKS1 has unsupported header size.

Conversion (both directions) must be performed on inactive device. There must not be active dm-crypt mapping established for LUKS header requested for conversion.

--type option is mandatory with following accepted values: luks1 or luks2.

WARNING: The convert action can destroy the LUKS header in the case of a crash during conversion or if a media error occurs. Always create a header backup before performing this operation!

<options> can be [--header, --type].

config <device>

Set permanent configuration options (store to LUKS header). The config command is supported only for LUKS2.

The permanent options can be --priority to set priority (normal, prefer, ignore) for keyslot (specified by --key-slot) or --label and --subsystem.

<options> can be [--priority, --label, --subsystem, --key-slot, --header].