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].
