"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "man/cryptsetup.8" between
cryptsetup-2.3.6.tar.xz and cryptsetup-2.4.0.tar.xz

About: cryptsetup is a utility used to conveniently setup disk encryption based on the dm-crypt kernel module. These include plain dm-crypt volumes, LUKS volumes, loop-AES and TrueCrypt compatible format.

cryptsetup.8  (cryptsetup-2.3.6.tar.xz):cryptsetup.8  (cryptsetup-2.4.0.tar.xz)
skipping to change at line 81 skipping to change at line 81
the standard <device> <name> order. the standard <device> <name> order.
close <name> close <name>
Removes the existing mapping <name> and wipes the key from kernel memory. Removes the existing mapping <name> and wipes the key from kernel memory.
For backward compatibility there are close command aliases: remove, plainClose, luksClose, For backward compatibility there are close command aliases: remove, plainClose, luksClose,
loopaesClose, tcryptClose (all behaves exactly the same, device type is determined automatically loopaesClose, tcryptClose (all behaves exactly the same, device type is determined automatically
from active device). from active device).
<options> can be [--deferred] <options> can be [--deferred] or [--cancel-deferred]
status <name> status <name>
Reports the status for the mapping <name>. Reports the status for the mapping <name>.
resize <name> resize <name>
Resizes an active mapping <name>. Resizes an active mapping <name>.
If --size (in 512-bytes sectors) or --device-size are not specifie d, the size is computed from the If --size (in 512-bytes sectors) or --device-size are not specifie d, the size is computed from the
skipping to change at line 104 skipping to change at line 104
device size is used. device size is used.
Note that this does not change the raw device geometry, it just changes how many sectors of the Note that this does not change the raw device geometry, it just changes how many sectors of the
raw device are represented in the mapped device. raw device are represented in the mapped device.
If cryptsetup detected volume key for active device loaded in k ernel keyring service, resize If cryptsetup detected volume key for active device loaded in k ernel keyring service, resize
action would first try to retrieve the key using a token and only if it failed it'd ask for a action would first try to retrieve the key using a token and only if it failed it'd ask for a
passphrase to unlock a keyslot (LUKS) or to derive a volume key ag ain (plain mode). The kernel passphrase to unlock a keyslot (LUKS) or to derive a volume key ag ain (plain mode). The kernel
keyring is used by default for LUKS2 devices. keyring is used by default for LUKS2 devices.
With LUKS2 device additional <options> can be [--token-id, --tok With LUKS2 device additional <options> can be [--token-id, --token
en-only, --key-slot, --key-file, -only, --token-type, --key-slot,
--keyfile-size, --keyfile-offset, --timeout, --disable-locks, --di --key-file, --keyfile-size, --keyfile-offset, --timeout, --d
sable-keyring]. isable-external-tokens, --dis-
able-locks, --disable-keyring].
refresh <name> refresh <name>
Refreshes parameters of active mapping <name>. Refreshes parameters of active mapping <name>.
Updates parameters of active device <name> without need to deact Updates parameters of active device <name> without need to d
ivate the device (and umount eactivate the device (and umount
filesystem). Currently it supports parameters refresh on followin filesystem). Currently it supports parameters refresh on following
g devices: LUKS1, LUKS2 (includ- devices: LUKS1, LUKS2 (includ-
ing authenticated encryption), plain crypt and loopaes. ing authenticated encryption), plain crypt and loopaes.
Mandatory parameters are identical to those of an open action for respective device type. Mandatory parameters are identical to those of an open action for respective device type.
You may change following parameters on all devices --pe rf-same_cpu_crypt, --perf-sub- You may change following parameters on all devices --p erf-same_cpu_crypt, --perf-sub-
mit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_wor kqueue and --allow-discards. mit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_wor kqueue and --allow-discards.
Refreshing device without any optional parameter will refresh the device with default setting Refreshing device without any optional parameter will refresh the device with default setting
(respective to device type). (respective to device type).
LUKS2 only: LUKS2 only:
--integrity-no-journal parameter affects only LUKS2 devices with u nderlying dm-integrity device. --integrity-no-journal parameter affects only LUKS2 devices with u nderlying dm-integrity device.
Adding option --persistent stores any combination of device parame ters above in LUKS2 metadata Adding option --persistent stores any combination of device pa rameters above in LUKS2 metadata
(only after successful refresh operation). (only after successful refresh operation).
--disable-keyring parameter refreshes a device with volume key pas sed in dm-crypt driver. --disable-keyring parameter refreshes a device with volume key pas sed in dm-crypt driver.
reencrypt <device> or --active-name <name> [<new_name>] reencrypt <device> or --active-name <name> [<new_name>]
Run resilient reencryption (LUKS2 device only). Run resilient reencryption (LUKS2 device only).
There are 3 basic modes of operation: There are 3 basic modes of operation:
· device reencryption (reencrypt) · device reencryption (reencrypt)
· device encryption (reencrypt --encrypt) · device encryption (reencrypt --encrypt)
· device decryption (reencrypt --decrypt) · device decryption (reencrypt --decrypt)
<device> or --active-name <name> is mandatory parameter. <device> or --active-name <name> is mandatory parameter.
With <device> parameter cryptsetup looks up active <device> dm m apping. If no active mapping is With <device> parameter cryptsetup looks up active <device> dm map ping. If no active mapping is
detected, it starts offline reencryption otherwise online reencryp tion takes place. detected, it starts offline reencryption otherwise online reencryp tion takes place.
Reencryption process may be safely interrupted by a user via SIGTE RM signal (ctrl+c). Reencryption process may be safely interrupted by a user via SIGTE RM signal (ctrl+c).
To resume already initialized or interrupted reencryption, just ru To resume already initialized or interrupted reencryption, just r
n the cryptsetup reencrypt com- un the cryptsetup reencrypt com-
mand again to continue the reencryption operation. Reencrypti mand again to continue the reencryption operation. Reencryption m
on may be resumed with different ay be resumed with different
--resilience or --hotzone-size unless implicit datashift resili --resilience or --hotzone-size unless implicit datashift res
ence mode is used (reencrypt ilience mode is used (reencrypt
--encrypt with --reduce-device-size option). --encrypt with --reduce-device-size option).
If the reencryption process was interrupted abruptly (reencrypt If the reencryption process was interrupted abruptly (reencryption
ion process crash, system crash, process crash, system crash,
poweroff) it may require recovery. The recovery is currently run a poweroff) it may require recovery. The recovery is currently run
utomatically on next activation automatically on next activation
(action open) when needed. (action open) when needed.
Optional parameter <new_name> takes effect only with --encryp Optional parameter <new_name> takes effect only with --encrypt op
t option and it activates device tion and it activates device
<new_name> immediately after encryption initialization gets finish <new_name> immediately after encryption initialization gets fin
ed. That's useful when device ished. That's useful when device
needs to be ready as soon as possible and mounted (used) before f needs to be ready as soon as possible and mounted (used) before fu
ull data area encryption is com- ll data area encryption is com-
pleted. pleted.
Action supports following additional <options> [--encrypt, --decry pt, --device-size, --resilience, Action supports following additional <options> [--encrypt, --decry pt, --device-size, --resilience,
--resilience-hash, --hotzone-size, --init-only, --resume-only , --reduce-device-size, --mas- --resilience-hash, --hotzone-size, --init-only, --resume-only, --reduce-device-size, --mas-
ter-key-file, --key-size]. ter-key-file, --key-size].
PLAIN MODE PLAIN MODE
Plain dm-crypt encrypts the device sector-by-sector with a single, non-sa Plain dm-crypt encrypts the device sector-by-sector with a single, non-s
lted hash of the passphrase. No alted hash of the passphrase. No
checks are performed, no metadata is used. There is no formatting op checks are performed, no metadata is used. There is no formatting operati
eration. When the raw device is on. When the raw device is
mapped (opened), the usual device operations can be used on the mapped de mapped (opened), the usual device operations can be used on the mapped d
vice, including filesystem cre- evice, including filesystem cre-
ation. Mapped devices usually reside in /dev/mapper/<name>. ation. Mapped devices usually reside in /dev/mapper/<name>.
The following are valid plain device type actions: The following are valid plain device type actions:
open --type plain <device> <name> open --type plain <device> <name>
create <name> <device> (OBSOLETE syntax) create <name> <device> (OBSOLETE syntax)
Opens (creates a mapping with) <name> backed by device <device>. Opens (creates a mapping with) <name> backed by device <device>.
<options> can be [--hash, --cipher, --verify-passphrase, --sector- size, --key-file, --keyfile-off- <options> can be [--hash, --cipher, --verify-passphrase, --sector- size, --key-file, --keyfile-off-
set, --key-size, --offset, --skip, --size, --readonly, --shared, - -allow-discards, --refresh] set, --key-size, --offset, --skip, --size, --readonly, --shared, - -allow-discards, --refresh]
Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the raw Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the ra
encrypted device /dev/sda10 to w encrypted device /dev/sda10 to
the mapped (decrypted) device /dev/mapper/e1, which can the the mapped (decrypted) device /dev/mapper/e1, which can then be
n be mounted, fsck-ed or have a mounted, fsck-ed or have a
filesystem created on it. filesystem created on it.
LUKS EXTENSION LUKS EXTENSION
LUKS, the Linux Unified Key Setup, is a standard for disk encryption. It LUKS, the Linux Unified Key Setup, is a standard for disk encryption.
adds a standardized header at It adds a standardized header at
the start of the device, a key-slot area directly behind the header and the start of the device, a key-slot area directly behind the header and t
the bulk data area behind that. he bulk data area behind that.
The whole set is called a 'LUKS container'. The device that a LUKS conta The whole set is called a 'LUKS container'. The device that a LUKS
iner resides on is called a container resides on is called a
'LUKS device'. For most purposes, both terms can be used interchangea 'LUKS device'. For most purposes, both terms can be used interchangeably
bly. But note that when the LUKS . But note that when the LUKS
header is at a nonzero offset in a device, then the device is not a LUKS header is at a nonzero offset in a device, then the device is not a LUK
device anymore, but has a LUKS S device anymore, but has a LUKS
container stored in it at an offset. container stored in it at an offset.
LUKS can manage multiple passphrases that can be individually revoked or changed and that can be securely 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. P assphrases are protected against scrubbed from persistent media due to the use of anti-forensic stripes. P assphrases are protected against
brute-force and dictionary attacks by PBKDF2, which implements hash it eration and salting in one func- brute-force and dictionary attacks by PBKDF2, which implements hash itera tion and salting in one func-
tion. tion.
LUKS2 is a new version of header format that allows additional extensions LUKS2 is a new version of header format that allows additional extension
like different PBKDF algorithm s like different PBKDF algorithm
or authenticated encryption. You can format device with LUKS2 heade or authenticated encryption. You can format device with LUKS2 header if
r if you specify --type luks2 in you specify --type luks2 in
luksFormat command. For activation, the format is already recognized aut omatically. luksFormat command. For activation, the format is already recognized aut omatically.
Each passphrase, also called a key in this document, is associated with o Each passphrase, also called a key in this document, is associated with
ne of 8 key-slots. Key opera- one of 8 key-slots. Key opera-
tions that do not specify a slot affect the first slot that matches the tions that do not specify a slot affect the first slot that matches the s
supplied passphrase or the first upplied passphrase or the first
empty slot if a new passphrase is added. empty slot if a new passphrase is added.
The <device> parameter can also be specified by a LUKS UUID in the forma t UUID=<uuid>. Translation to The <device> parameter can also be specified by a LUKS UUID in the fo rmat UUID=<uuid>. Translation to
real device name uses symlinks in /dev/disk/by-uuid directory. real device name uses symlinks in /dev/disk/by-uuid directory.
To specify a detached header, the --header parameter can be used in al l LUKS commands and always takes To specify a detached header, the --header parameter can be used in all L UKS commands and always takes
precedence over the positional <device> parameter. precedence over the positional <device> parameter.
The following are valid LUKS actions: The following are valid LUKS actions:
luksFormat <device> [<key file>] luksFormat <device> [<key file>]
Initializes a LUKS partition and sets the initial passphrase (for Initializes a LUKS partition and sets the initial passphrase (for
key-slot 0), either via prompt- key-slot 0), either via prompt-
ing or via <key file>. Note that if the second argument is prese ing or via <key file>. Note that if the second argument is present
nt, then the passphrase is taken , then the passphrase is taken
from the file given there, without the need to use the --key-file from the file given there, without the need to use the --key-file
option. Also note that for both option. Also note that for both
forms of reading the passphrase from a file you can give '-' as forms of reading the passphrase from a file you can give '-' as fi
file name, which results in the le name, which results in the
passphrase being read from stdin and the safety-question being ski pped. passphrase being read from stdin and the safety-question being ski pped.
You cannot call luksFormat on a device or filesystem that is map You cannot call luksFormat on a device or filesystem that i
ped or in use, e.g. mounted s mapped or in use, e.g. mounted
filesysem, used in LVM, active RAID member etc. The device or fi filesysem, used in LVM, active RAID member etc. The device or fil
lesystem has to be un-mounted in esystem has to be un-mounted in
order to call luksFormat. order to call luksFormat.
To use LUKS2, specify --type luks2. To use LUKS2, specify --type luks2.
<options> can be [--hash, --cipher, --verify-passphrase, --key-siz e, --key-slot, --key-file (takes <options> can be [--hash, --cipher, --verify-passphrase, --key-siz e, --key-slot, --key-file (takes
precedence over optional second argument), --keyfile-offset, precedence over optional second argument), --keyfile-offset,
--keyfile-size, --use-random | --keyfile-size, --use-random |
--use-urandom, --uuid, --master-key-file, --iter-time, --hea --use-urandom, --uuid, --master-key-file, --iter-time, --he
der, --pbkdf-force-iterations, ader, --pbkdf-force-iterations,
--force-password, --disable-locks]. --force-password, --disable-locks].
For LUKS2, additional <options> can be [--integrity, --integrity- For LUKS2, additional <options> can be [--integrity, --integrity-n
no-wipe, --sector-size, --label, o-wipe, --sector-size, --label,
--subsystem, --pbkdf, --pbkdf-memory, --pbkdf-parallel, --dis --subsystem, --pbkdf, --pbkdf-memory, --pbkdf-parallel, --di
able-locks, --disable-keyring, sable-locks, --disable-keyring,
--luks2-metadata-size, --luks2-keyslots-size, --keyslot-cipher, -- keyslot-key-size]. --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 WARNING: Doing a luksFormat on an existing LUKS container will mak e all data the old container
permanently irretrievable unless you have a header backup. permanently irretrievable unless you have a header backup.
open --type luks <device> <name> open --type luks <device> <name>
luksOpen <device> <name> (old syntax) luksOpen <device> <name> (old syntax)
Opens the LUKS device <device> and sets up a mapping <name> after successful verification of the Opens the LUKS device <device> and sets up a mapping <name> afte r successful verification of the
supplied passphrase. supplied passphrase.
First, the passphrase is searched in LUKS tokens. If it's not found in any token and also the First, the passphrase is searched in LUKS tokens. If it's not foun d in any token and also the
passphrase is not supplied via --key-file, the command prompts for it interactively. passphrase is not supplied via --key-file, the command prompts for it interactively.
<options> can be [--key-file, --keyfile-offset, --keyfile-size, <options> can be [--key-file, --keyfile-offset, --keyfile-size
--readonly, --test-passphrase, , --readonly, --test-passphrase,
--allow-discards, --header, --key-slot, --master-key-file, -- --allow-discards, --header, --key-slot, --master-key-file, --token
token-id, --token-only, --dis- -id, --token-only, --token-type,
able-keyring, --disable-locks, --type, --refresh, --serialize-memo --disable-external-tokens, --disable-keyring, --disable-locks, --t
ry-hard-pbkdf]. ype, --refresh, --serialize-mem-
ory-hard-pbkdf].
luksSuspend <name> luksSuspend <name>
Suspends an active device (all IO operations will block and acces ses to the device will wait Suspends an active device (all IO operations will block and acces ses to the device will wait
indefinitely) and wipes the encryption key from kernel memory. Nee ds kernel 2.6.19 or later. indefinitely) and wipes the encryption key from kernel memory. Nee ds kernel 2.6.19 or later.
After this operation you have to use luksResume to reinstate th e encryption key and unblock the After this operation you have to use luksResume to reinstate th e encryption key and unblock the
device or close to remove the mapped device. device or close to remove the mapped device.
WARNING: never suspend the device on which the cryptsetup binary r esides. WARNING: never suspend the device on which the cryptsetup binary r esides.
skipping to change at line 395 skipping to change at line 397
to decrypt the data stored in the LUKS container without a passphr ase and even without the LUKS to decrypt the data stored in the LUKS container without a passphr ase and even without the LUKS
header. This means that if the master key is compromised, the whole device has to be erased or 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. reencrypted to prevent further access. Use this option carefully.
To dump the master key, a passphrase has to be supplied, either in teractively or via --key-file. To dump the master key, a passphrase has to be supplied, either in teractively or via --key-file.
To dump unbound key (LUKS2 format only), --unbound parameter, spec ific --key-slot id and proper To dump unbound key (LUKS2 format only), --unbound parameter, spec ific --key-slot id and proper
passphrase has to be supplied, either interactively or via --key-f ile. Optional --master-key-file passphrase has to be supplied, either interactively or via --key-f ile. Optional --master-key-file
parameter enables unbound keyslot dump to a file. parameter enables unbound keyslot dump to a file.
<options> can be [--dump-master-key, --key-file, --keyfile-off To dump LUKS2 JSON metadata (without basic heade information like
set, --keyfile-size, --header, UUID) use --dump-json-metadata
--disable-locks, --master-key-file, --type, --unbound, --key-slot] option.
.
<options> can be [--dump-master-key, --dump-json-metadata, --ke
y-file, --keyfile-offset, --key-
file-size, --header, --disable-locks, --master-key-file, --type, -
-unbound, --key-slot].
WARNING: If --dump-master-key is used with --key-file and the a rgument to --key-file is '-', no WARNING: If --dump-master-key is used with --key-file and the argu ment to --key-file is '-', no
validation question will be asked and no warning given. validation question will be asked and no warning given.
luksHeaderBackup <device> --header-backup-file <file> luksHeaderBackup <device> --header-backup-file <file>
Stores a binary backup of the LUKS header and keyslot area. Stores a binary backup of the LUKS header and keyslot area.
Note: Using '-' as filename writes the header backup to a file nam ed '-'. Note: Using '-' as filename writes the header backup to a file nam ed '-'.
WARNING: This backup file and a passphrase valid at the time of ba WARNING: This backup file and a passphrase valid at the time of
ckup allows decryption of the backup allows decryption of the
LUKS data area, even if the passphrase was later changed or re LUKS data area, even if the passphrase was later changed or remove
moved from the LUKS device. Also d from the LUKS device. Also
note that with a header backup you lose the ability to securely wi pe the LUKS device by just over- note that with a header backup you lose the ability to securely wi pe the LUKS device by just over-
writing the header and key-slots. You either need to securely eras e all header backups in addition writing the header and key-slots. You either need to securely eras e all header backups in addition
or overwrite the encrypted data area as well. The second option i s less secure, as some sectors 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. can survive, e.g. due to defect management.
luksHeaderRestore <device> --header-backup-file <file> luksHeaderRestore <device> --header-backup-file <file>
Restores a binary backup of the LUKS header and keyslot area from the specified 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 na med '-'. Note: Using '-' as filename reads the header backup from a file na med '-'.
WARNING: Header and keyslots will be replaced, only the passp hrases from the backup will work WARNING: Header and keyslots will be replaced, only the passphrase s from the backup will work
afterward. afterward.
This command requires that the master key size and data offset of This command requires that the master key size and data offset o
the LUKS header already on the f the LUKS header already on the
device and of the header backup match. Alternatively, if there device and of the header backup match. Alternatively, if there is
is no LUKS header on the device, no LUKS header on the device,
the backup will also be written to it. the backup will also be written to it.
token <add|remove|import|export> <device> token <add|remove|import|export> <device>
Action add creates new keyring token to enable auto-activation of Action add creates new keyring token to enable auto-activation of
the device. For the auto-acti- the device. For the auto-acti-
vation, the passphrase must be stored in keyring with the spe vation, the passphrase must be stored in keyring with the specif
cified description. Usually, the ied description. Usually, the
passphrase should be stored in user or user-session keyring. The passphrase should be stored in user or user-session keyring. The
token command is supported only token command is supported only
for LUKS2. for LUKS2.
For adding new keyring token, option --key-description is mandato For adding new keyring token, option --key-description is mandator
ry. Also, new token is assigned y. Also, new token is assigned
to key slot specified with --key-slot option or to all active key to key slot specified with --key-slot option or to all active
slots in the case --key-slot key slots in the case --key-slot
option is omitted. option is omitted.
To remove existing token, specify the token ID which should be rem oved with --token-id option. To remove existing token, specify the token ID which should be rem oved with --token-id option.
WARNING: The action token remove removes any token type, not j ust keyring type from token slot WARNING: The action token remove removes any token type, not just keyring type from token slot
specified by --token-id option. specified by --token-id option.
Action import can store arbitrary valid token json in LUKS2 header Action import can store arbitrary valid token json in LUKS2 heade
. It may be passed via standard r. It may be passed via standard
input or via file passed in --json-file option. If you spec input or via file passed in --json-file option. If you specify
ify --key-slot then successfully --key-slot then successfully
imported token is also assigned to the key slot. 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. 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-descri <options> can be [--header, --token-id, --key-slot, --key-descrip
ption, --disable-locks, --dis- tion, --disable-external-tokens,
able-keyring, --json-file]. --disable-locks, --disable-keyring, --json-file].
convert <device> --type <format> convert <device> --type <format>
Converts the device between LUKS1 and LUKS2 format (if possible). The conversion will not be per- Converts the device between LUKS1 and LUKS2 format (if possible). The conversion will not be per-
formed if there is an additional LUKS2 feature or LUKS1 has unsupp orted header size. formed if there is an additional LUKS2 feature or LUKS1 has unsupp orted header size.
Conversion (both directions) must be performed on inactive device. There must not be active dm- Conversion (both directions) must be performed on inactive devi ce. There must not be active dm-
crypt mapping established for LUKS header requested for conversion . crypt mapping established for LUKS header requested for conversion .
--type option is mandatory with following accepted values: luks1 o r luks2. --type option is mandatory with following accepted values: luks1 o r luks2.
WARNING: The convert action can destroy the LUKS header in the c ase of a crash during conversion WARNING: The convert action can destroy the LUKS header in the cas e of a crash during conversion
or if a media error occurs. Always create a header backup before performing this operation! or if a media error occurs. Always create a header backup before performing this operation!
<options> can be [--header, --type]. <options> can be [--header, --type].
config <device> config <device>
Set permanent configuration options (store to LUKS header). The c onfig command is supported only Set permanent configuration options (store to LUKS header). The config command is supported only
for LUKS2. for LUKS2.
The permanent options can be --priority to set priority (nor mal, prefer, ignore) for keyslot The permanent options can be --priority to set priority (normal, prefer, ignore) for keyslot
(specified by --key-slot) or --label and --subsystem. (specified by --key-slot) or --label and --subsystem.
<options> can be [--priority, --label, --subsystem, --key-slot, -- header]. <options> can be [--priority, --label, --subsystem, --key-slot, -- header].
loop-AES EXTENSION loop-AES EXTENSION
cryptsetup supports mapping loop-AES encrypted partition using a compatib ility mode. cryptsetup supports mapping loop-AES encrypted partition using a compatib ility mode.
open --type loopaes <device> <name> --key-file <keyfile> open --type loopaes <device> <name> --key-file <keyfile>
loopaesOpen <device> <name> --key-file <keyfile> (old syntax) loopaesOpen <device> <name> --key-file <keyfile> (old syntax)
Opens the loop-AES <device> and sets up a mapping <name>. Opens the loop-AES <device> and sets up a mapping <name>.
If the key file is encrypted with GnuPG, then you have to use --ke y-file=- and decrypt it before If the key file is encrypted with GnuPG, then you have to use -- key-file=- and decrypt it before
use, e.g. like this: use, e.g. like this:
gpg --decrypt <keyfile> | cryptsetup loopaesOpen --key-file=- <dev ice> <name> gpg --decrypt <keyfile> | cryptsetup loopaesOpen --key-file=- <dev ice> <name>
WARNING: The loop-AES extension cannot use the direct input of k ey file on real terminal because WARNING: The loop-AES extension cannot use the direct input of key file on real terminal because
the keys are separated by end-of-line and only part of the multi-k ey file would be read. the keys are separated by end-of-line and only part of the multi-k ey file would be read.
If you need it in script, just use the pipe redirection: If you need it in script, just use the pipe redirection:
echo $keyfile | cryptsetup loopaesOpen --key-file=- <device> <name > echo $keyfile | cryptsetup loopaesOpen --key-file=- <device> <name >
Use --keyfile-size to specify the proper key length if needed. Use --keyfile-size to specify the proper key length if needed.
Use --offset to specify device offset. Note that the units need to be specified in number of 512 Use --offset to specify device offset. Note that the units need to be specified in number of 512
byte sectors. byte sectors.
Use --skip to specify the IV offset. If the original device used Use --skip to specify the IV offset. If the original device used a
an offset and but did not use it n offset and but did not use it
in IV sector calculations, you have to explicitly use --skip 0 in in IV sector calculations, you have to explicitly use --skip 0 i
addition to the offset parame- n addition to the offset parame-
ter. ter.
Use --hash to override the default hash function for passphrase h ashing (otherwise it is detected Use --hash to override the default hash function for passphrase ha shing (otherwise it is detected
according to key size). according to key size).
<options> can be [--key-file, --key-size, --offset, --skip, --hash , --readonly, --allow-discards, <options> can be [--key-file, --key-size, --offset, --skip, --has h, --readonly, --allow-discards,
--refresh]. --refresh].
See also section 7 of the FAQ and http://loop-aes.sourceforge.net for more information regarding loop- See also section 7 of the FAQ and http://loop-aes.sourceforge.net for mor e information regarding loop-
AES. AES.
TCRYPT (TrueCrypt-compatible and VeraCrypt) EXTENSION TCRYPT (TrueCrypt-compatible and VeraCrypt) EXTENSION
cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt (with --ver cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt encrypte
acrypt option) encrypted parti- d partition using a native Linux
tion using a native Linux kernel API. Header formatting and TCRYPT kernel API. Header formatting and TCRYPT header change is not supported,
header change is not supported, cryptsetup never changes TCRYPT
cryptsetup never changes TCRYPT header on-device. header on-device.
TCRYPT extension requires kernel userspace crypto API to be available TCRYPT extension requires kernel userspace crypto API to be avail
(introduced in Linux kernel able (introduced in Linux kernel
2.6.38). If you are configuring kernel yourself, enable "User-space in 2.6.38). If you are configuring kernel yourself, enable "User-space inte
terface for symmetric key cipher rface for symmetric key cipher
algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .con fig option). algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .con fig option).
Because TCRYPT header is encrypted, you have to always provide valid pass phrase and keyfiles. Because TCRYPT header is encrypted, you have to always provide valid pass phrase and keyfiles.
Cryptsetup should recognize all header variants, except legacy cipher cha Cryptsetup should recognize all header variants, except legacy cipher
ins using LRW encryption mode chains using LRW encryption mode
with 64 bits encryption block (namely Blowfish in LRW mode is not recogn with 64 bits encryption block (namely Blowfish in LRW mode is not recogni
ized, this is limitation of ker- zed, this is limitation of ker-
nel crypto API). nel crypto API).
To recognize a VeraCrypt device use the --veracrypt option. VeraCrypt is VeraCrypt is just extension of TrueCrypt header with increased itera
just extension of TrueCrypt tion count so unlocking can take
header with increased iteration count so unlocking can take quite a quite a lot of time (in comparison with TCRYPT device).
lot of time (in comparison with
TCRYPT device). To open a VeraCrypt device with a custom Personal Iteration Multiplier (P
IM) value, use either the --ver-
To open a VeraCrypt device with a custom Personal Iteration Multiplier acrypt-pim=<PIM> option to directly specify the PIM on the command- line
(PIM) value, additionally to or use --veracrypt-query-pim to
--veracrypt use either the --veracrypt-pim=<PIM> option to directly spec be prompted for the PIM.
ify the PIM on the command- line
or use --veracrypt-query-pim to be prompted for the PIM.
The PIM value affects the number of iterations applied during key derivation. Please refer to The PIM value affects the number of iterations applied during key derivation. Please refer to
https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%2 9.html for more detailed infor- https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%2 9.html for more detailed infor-
mation. mation.
If you need to disable VeraCrypt device support, use --disable-veracrypt
option.
NOTE: Activation with tcryptOpen is supported only for cipher chains usin g LRW or XTS encryption modes. NOTE: Activation with tcryptOpen is supported only for cipher chains usin g LRW or XTS encryption modes.
The tcryptDump command should work for all recognized TCRYPT devices and doesn't require superuser privi- The tcryptDump command should work for all recognized TCRYPT devices and doesn't require superuser privi-
lege. lege.
To map system device (device with boot loader where the whole encrypted s ystem resides) use --tcrypt-sys- To map system device (device with boot loader where the whole encrypted s ystem resides) use --tcrypt-sys-
tem option. You can use partition device as the parameter (parameter mus t be real partition device, not tem option. You can use partition device as the parameter (parameter mus t be real partition device, not
an image in a file), then only this partition is mapped. an image in a file), then only this partition is mapped.
If you have the whole TCRYPT device as a file image and you want to map m ultiple partition encrypted with If you have the whole TCRYPT device as a file image and you want to map m ultiple partition encrypted with
skipping to change at line 568 skipping to change at line 574
NOTE: There is no protection for a hidden volume if the outer volume i s mounted. The reason is that if NOTE: There is no protection for a hidden volume if the outer volume i s mounted. The reason is that if
there were any protection, it would require some metadata describing what to protect in the outer volume there were any protection, it would require some metadata describing what to protect in the outer volume
and the hidden volume would become detectable. and the hidden volume would become detectable.
open --type tcrypt <device> <name> open --type tcrypt <device> <name>
tcryptOpen <device> <name> (old syntax) tcryptOpen <device> <name> (old syntax)
Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a m apping <name>. Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a m apping <name>.
<options> can be [--key-file, --tcrypt-hidden, --tcrypt-syste m, --tcrypt-backup, --readonly, <options> can be [--key-file, --tcrypt-hidden, --tcrypt-syste m, --tcrypt-backup, --readonly,
--test-passphrase, --allow-discards, --veracrypt, --veracryp --test-passphrase, --allow-discards, --disable-veracrypt, --veracr
t-pim, --veracrypt-query-pim, ypt-pim, --veracrypt-query-pim,
--header]. --header, --cipher, --hash].
The keyfile parameter allows a combination of file content with the passphrase and can be The keyfile parameter allows a combination of file content with the passphrase and can be
repeated. Note that using keyfiles is compatible with TCRYPT and i s different from LUKS keyfile repeated. Note that using keyfiles is compatible with TCRYPT and i s different from LUKS keyfile
logic. logic.
If you use --header in combination with hidden or system optio If --PBKDF2 variants with the specified hash algorithms are checke
ns, the header file must contain d. This could speed up unlocking
the device (but also it reveals some information about the contain
er).
If you use --header in combination with hidden or system options,
the header file must contain
specific headers on the same positions as the original encrypted c ontainer. specific headers on the same positions as the original encrypted c ontainer.
WARNING: Option --allow-discards cannot be combined with option -- WARNING: Option --allow-discards cannot be combined with option
tcrypt-hidden. For normal map- --tcrypt-hidden. For normal map-
ping, it can cause the destruction of hidden volume (hidden vo ping, it can cause the destruction of hidden volume (hidden volume
lume appears as unused space for appears as unused space for
outer volume so this space can be discarded). outer volume so this space can be discarded).
tcryptDump <device> tcryptDump <device>
Dump the header information of a TCRYPT device. Dump the header information of a TCRYPT device.
If the --dump-master-key option is used, the TCRYPT device master If the --dump-master-key option is used, the TCRYPT device master
key is dumped instead of TCRYPT key is dumped instead of TCRYPT
header info. Beware that the master key (or concatenated master k header info. Beware that the master key (or concatenated master ke
eys if cipher chain is used) can ys if cipher chain is used) can
be used to decrypt the data stored in the TCRYPT container without be used to decrypt the data stored in the TCRYPT container withou
a passphrase. This means that t a passphrase. This means that
if the master key is compromised, the whole device has to be erase d to prevent further access. Use if the master key is compromised, the whole device has to be erase d to prevent further access. Use
this option carefully. this option carefully.
<options> can be [--dump-master-key, --key-file, --tc <options> can be [--dump-master-key, --key-file, --t
rypt-hidden, --tcrypt-system, crypt-hidden, --tcrypt-system,
--tcrypt-backup]. --tcrypt-backup, --cipher, --hash].
The keyfile parameter allows a combination of file content with the passphrase and can be The keyfile parameter allows a combination of file content wit h the passphrase and can be
repeated. repeated.
See also https://en.wikipedia.org/wiki/TrueCrypt for more information reg arding TrueCrypt. See also https://en.wikipedia.org/wiki/TrueCrypt for more information reg arding TrueCrypt.
Please note that cryptsetup does not use TrueCrypt code, please report al l problems related to this com- Please note that cryptsetup does not use TrueCrypt code, please report a ll problems related to this com-
patibility extension to the cryptsetup project. patibility extension to the cryptsetup project.
BITLK (Windows BitLocker-compatible) EXTENSION (EXPERIMENTAL) BITLK (Windows BitLocker-compatible) EXTENSION (EXPERIMENTAL)
cryptsetup supports mapping of BitLocker and BitLocker to Go encrypte d partition using a native Linux cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted pa rtition using a native Linux
kernel API. Header formatting and BITLK header changes are not supported , cryptsetup never changes BITLK kernel API. Header formatting and BITLK header changes are not supported , cryptsetup never changes BITLK
header on-device. header on-device.
WARNING: This extension is EXPERIMENTAL. WARNING: This extension is EXPERIMENTAL.
BITLK extension requires kernel userspace crypto API to be available (for details see TCRYPT section). BITLK extension requires kernel userspace crypto API to be available (for details see TCRYPT section).
Cryptsetup should recognize all BITLK header variants, except legacy head er used in Windows Vista systems Cryptsetup should recognize all BITLK header variants, except legacy head er used in Windows Vista systems
and partially decrypted BitLocker devices. Activation of legacy devices encrypted in CBC mode requires and partially decrypted BitLocker devices. Activation of legacy device s encrypted in CBC mode requires
at least Linux kernel version 5.3 and for devices using Elephant diffuser kernel 5.6. at least Linux kernel version 5.3 and for devices using Elephant diffuser kernel 5.6.
The bitlkDump command should work for all recognized BITLK devices and doesn't require superuser privi- The bitlkDump command should work for all recognized BITLK devices and do esn't require superuser privi-
lege. lege.
For unlocking with the open a password or a recovery passphrase must be p For unlocking with the open a password or a recovery passphrase or a star
rovided. Other unlocking methods tup key must be provided.
(TPM, SmartCard) are not supported.
Additionally unlocking using master key is supported. You must provide
BitLocker Full Volume Encryption
Key (FVEK) using the --master-key-file option. The key must be decrypted
and without the header (only
128/256/512 bits of key data depending on used cipher and mode).
Other unlocking methods (TPM, SmartCard) are not supported.
open --type bitlk <device> <name> open --type bitlk <device> <name>
bitlkOpen <device> <name> (old syntax) bitlkOpen <device> <name> (old syntax)
Opens the BITLK (a BitLocker-compatible) <device> and sets up a ma pping <name>. Opens the BITLK (a BitLocker-compatible) <device> and sets up a ma pping <name>.
<options> can be [--key-file, --readonly, --test-passphrase, --all ow-discards]. <options> can be [--key-file, --readonly, --test-passphrase, --all ow-discards --master-key-file].
bitlkDump <device> bitlkDump <device>
Dump the header information of a BITLK device. Dump the header information of a BITLK device.
Please note that cryptsetup does not use any Windows BitLocker <options> can be [--dump-master-key --master-key-file].
code, please report all problems
related to this compatibility extension to the cryptsetup project. Please note that cryptsetup does not use any Windows BitLocker code, pl
ease report all problems related
to this compatibility extension to the cryptsetup project.
MISCELLANEOUS MISCELLANEOUS
repair <device> repair <device>
Tries to repair the device metadata if possible. Currently support ed only for LUKS device type. Tries to repair the device metadata if possible. Currently support ed only for LUKS device type.
This command is useful to fix some known benign LUKS metadata head er corruptions. Only basic cor- This command is useful to fix some known benign LUKS metadata head er corruptions. Only basic cor-
ruptions of unused keyslot are fixable. This command will only change the LUKS header, not any ruptions of unused keyslot are fixable. This command will only change the LUKS header, not any
key-slot data. You may enforce LUKS version by adding --type optio n. key-slot data. You may enforce LUKS version by adding --type optio n.
skipping to change at line 764 skipping to change at line 780
file instead of being printed out to standard output. file instead of being printed out to standard output.
WARNING: If you create your own master key, you need to make sure to do it right. Otherwise, you WARNING: If you create your own master key, you need to make sure to do it right. Otherwise, you
can end up with a low-entropy or otherwise partially predictable master key which will compromise can end up with a low-entropy or otherwise partially predictable master key which will compromise
security. security.
For luksAddKey this allows adding a new passphrase without having to know an existing one. For luksAddKey this allows adding a new passphrase without having to know an existing one.
For open this allows one to open the LUKS device without giving a passphrase. For open this allows one to open the LUKS device without giving a passphrase.
--dump-json-metadata
For luksDump (LUKS2 only) this option prints content of LUKS2 head
er JSON metadata area.
--dump-master-key --dump-master-key
For luksDump this option includes the master key in the displayed information. Use with care, as For luksDump this option includes the master key in the displayed information. Use with care, as
the master key can be used to bypass the passphrases, see also opt ion --master-key-file. the master key can be used to bypass the passphrases, see also opt ion --master-key-file.
--json-file --json-file
Read token json from a file or write token to it. See to ken action for more information. Read token json from a file or write token to it. See to ken action for more information.
--json-file=- reads json from standard input or writes it to stand ard output respectively. --json-file=- reads json from standard input or writes it to stand ard output respectively.
--use-random --use-random
skipping to change at line 785 skipping to change at line 804
For luksFormat these options define which kernel random number gen erator will be used to create For luksFormat these options define which kernel random number gen erator will be used to create
the master key (which is a long-term key). the master key (which is a long-term key).
See NOTES ON RANDOM NUMBER GENERATORS for more information. Use cr yptsetup --help to show the com- See NOTES ON RANDOM NUMBER GENERATORS for more information. Use cr yptsetup --help to show the com-
piled-in default random number generator. piled-in default random number generator.
WARNING: In a low-entropy situation (e.g. in an embedded system), both selections are problematic. WARNING: In a low-entropy situation (e.g. in an embedded system), both selections are problematic.
Using /dev/urandom can lead to weak keys. Using /dev/random ca n block a long time, potentially Using /dev/urandom can lead to weak keys. Using /dev/random ca n block a long time, potentially
forever, if not enough entropy can be harvested by the kernel. forever, if not enough entropy can be harvested by the kernel.
--key-slot, -S <0-7> --key-slot, -S <0-N>
For LUKS operations that add key material, this options allows you to specify which key slot is For LUKS operations that add key material, this options allows you to specify which key slot is
selected for the new key. This option can be used for luksFormat, and luksAddKey. selected for the new key. This option can be used for luksFormat, and luksAddKey.
In addition, for open, this option selects a specific key-slot to compare the passphrase against. In addition, for open, this option selects a specific key-slot to compare the passphrase against.
If the given passphrase would only match a different key-slot, the operation fails. If the given passphrase would only match a different key-slot, the operation fails.
Maximum number of key slots depends on LUKS version. LUKS1 can hav
e up to 8 key slots. LUKS2 can
have up to 32 key slots based on key slot area size and key s
ize, but a valid key slot ID can
always be between 0 and 31 for LUKS2.
--key-size, -s <bits> --key-size, -s <bits>
Sets key size in bits. The argument has to be a multiple of 8. The possible key-sizes are limited Sets key size in bits. The argument has to be a multiple of 8. The possible key-sizes are limited
by the cipher and mode used. by the cipher and mode used.
See /proc/crypto for more information. Note that key-size in /proc /crypto is stated in bytes. See /proc/crypto for more information. Note that key-size in /proc /crypto is stated in bytes.
This option can be used for open --type plain or luksFormat. All other LUKS actions will use the This option can be used for open --type plain or luksFormat. All other LUKS actions will use the
key-size specified in the LUKS header. Use cryptsetup --help to s how the compiled-in defaults. key-size specified in the LUKS header. Use cryptsetup --help to s how the compiled-in defaults.
--size, -b <number of 512 byte sectors> --size, -b <number of 512 byte sectors>
skipping to change at line 861 skipping to change at line 884
A PBKDF is used for increasing dictionary and brute-force attack c ost for keyslot passwords. The A PBKDF is used for increasing dictionary and brute-force attack c ost for keyslot passwords. The
parameters can be time, memory and parallel cost. parameters can be time, memory and parallel cost.
For PBKDF2, only time cost (number of iterations) applies. For Argon2i/id, there is also memory For PBKDF2, only time cost (number of iterations) applies. For Argon2i/id, there is also memory
cost (memory required during the process of key derivation) and pa rallel cost (number of threads cost (memory required during the process of key derivation) and pa rallel cost (number of threads
that run in parallel during the key derivation. that run in parallel during the key derivation.
Note that increasing memory cost also increases time, so the fin al parameter values are measured Note that increasing memory cost also increases time, so the fin al parameter values are measured
by a benchmark. The benchmark tries to find iteration time (--iter -time) with required memory cost by a benchmark. The benchmark tries to find iteration time (--iter -time) with required memory cost
--pbkdf-memory. If it is not possible, the memory cost is decre ased as well. The parallel cost --pbkdf-memory. If it is not possible, the memory cost is decre ased as well. The parallel cost
--pbkdf-parallel is constant, is is checked against available CPU --pbkdf-parallel is constant and is checked against available CPU
cores (if not available, it is cores.
decreased) and the maximum parallel cost is 4.
You can see all PBKDF parameters for particular LUKS2 keyslot with luksDump command. You can see all PBKDF parameters for particular LUKS2 keyslot with luksDump command.
NOTE: If you do not want to use benchmark and want to spec NOTE: If you do not want to use benchmark and want to specify
ify all parameters directly, use all parameters directly, use
--pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel. --pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel
This will override the values . This will override the values
without benchmarking. Note it can cause extremely long unlo without benchmarking. Note it can cause extremely long unlocking
cking time. Use only in specific time. Use only in specific
cases, for example, if you know that the formatted device will be used on some small embedded sys- cases, for example, if you know that the formatted device will be used on some small embedded sys-
tem. In this case, the LUKS PBKDF2 digest will be set to the mini tem.
mum iteration count.
MINIMAL AND MAXIMAL PBKDF COSTS: For PBKDF2, the minimum iteration
count is 1000 and maximum is
4294967295 (maximum for 32bit unsigned integer). Memory and paral
lel costs are unused for PBKDF2.
For Argon2i and Argon2id, minimum iteration count (CPU cost) is 4
and maximum is 4294967295 (maxi-
mum for 32bit unsigned integer). Minimum memory cost is 32 KiB a
nd maximum is 4 GiB. (Limited by
addresable memory on some CPU platforms.) If the memory cost para
meter is benchmarked (not speci-
fied by a parameter) it is always in range from 64 MiB to 1 GiB.
The parallel cost minimum is 1
and maximum 4 (if enough CPUs cores are available, otherwise it is
decreased).
--iter-time, -i <number of milliseconds> --iter-time, -i <number of milliseconds>
The number of milliseconds to spend with PBKDF passphrase proces sing. This option is only rele- The number of milliseconds to spend with PBKDF passphrase processi ng. This option is only rele-
vant for LUKS operations that set or change passphrases, such as l uksFormat or luksAddKey. Speci- vant for LUKS operations that set or change passphrases, such as l uksFormat or luksAddKey. Speci-
fying 0 as parameter selects the compiled-in default. fying 0 as parameter selects the compiled-in default.
--pbkdf-memory <number> --pbkdf-memory <number>
Set the memory cost for PBKDF (for Argon2i/id the number represe Set the memory cost for PBKDF (for Argon2i/id the number represent
nts kilobytes). Note that it is s kilobytes). Note that it is
maximal value, PBKDF benchmark or available physical memory can de maximal value, PBKDF benchmark or available physical memory can
crease it. This option is not decrease it. This option is not
available for PBKDF2. available for PBKDF2.
--pbkdf-parallel <number> --pbkdf-parallel <number>
Set the parallel cost for PBKDF (number of threads, up to 4). N ote that it is maximal value, it Set the parallel cost for PBKDF (number of threads, up to 4). Not e that it is maximal value, it
is decreased automatically if CPU online count is lower. This opt ion is not available for PBKDF2. is decreased automatically if CPU online count is lower. This opt ion is not available for PBKDF2.
--pbkdf-force-iterations <num> --pbkdf-force-iterations <num>
Avoid PBKDF benchmark and set time cost (iterations) directly. It can be used for LUKS/LUKS2 Avoid PBKDF benchmark and set time cost (iterations) directly . It can be used for LUKS/LUKS2
device only. See --pbkdf option for more info. device only. See --pbkdf option for more info.
--batch-mode, -q --batch-mode, -q
Suppresses all confirmation questions. Use with care! Suppresses all confirmation questions. Use with care!
If the -y option is not specified, this option also switches off the passphrase verification for If the -y option is not specified, this option also switches off t he passphrase verification for
luksFormat. luksFormat.
--progress-frequency <seconds> --progress-frequency <seconds>
Print separate line every <seconds> with wipe progress. Print separate line every <seconds> with wipe progress.
--timeout, -t <number of seconds> --timeout, -t <number of seconds>
The number of seconds to wait before timeout on passphrase input The number of seconds to wait before timeout on passphrase in
via terminal. It is relevant put via terminal. It is relevant
every time a passphrase is asked, for example for open, luks every time a passphrase is asked, for example for open, luksForma
Format or luksAddKey. It has no t or luksAddKey. It has no
effect if used in conjunction with --key-file. effect if used in conjunction with --key-file.
This option is useful when the system should not stall if the user does not input a passphrase, This option is useful when the system should not stall if the u ser does not input a passphrase,
e.g. during boot. The default is a value of 0 seconds, which means to wait forever. e.g. during boot. The default is a value of 0 seconds, which means to wait forever.
--tries, -T --tries, -T
How often the input of the passphrase shall be retried. This option is relevant every time a How often the input of the passphrase shall be retried. This opti on is relevant every time a
passphrase is asked, for example for open, luksFormat or luksAddKe y. The default is 3 tries. passphrase is asked, for example for open, luksFormat or luksAddKe y. The default is 3 tries.
--align-payload <number of 512 byte sectors> --align-payload <number of 512 byte sectors>
Align payload at a boundary of value 512-byte sectors. This optio n is relevant for luksFormat. Align payload at a boundary of value 512-byte sectors. This optio n is relevant for luksFormat.
If not specified, cryptsetup tries to use the topology info provid If not specified, cryptsetup tries to use the topology info provi
ed by the kernel for the under- ded by the kernel for the under-
lying device to get the optimal alignment. If not available (or lying device to get the optimal alignment. If not available (or t
the calculated value is a multi- he calculated value is a multi-
ple of the default) data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte sectors). ple of the default) data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte sectors).
For a detached LUKS header, this option specifies the offset on th e data device. See also the For a detached LUKS header, this option specifies the offset on the data device. See also the
--header option. --header option.
WARNING: This option is DEPRECATED and has often unexpected impac WARNING: This option is DEPRECATED and has often unexpected impact
t to the data offset and keyslot to the data offset and keyslot
area size (for LUKS2) due to the complex rounding. For fixed dat area size (for LUKS2) due to the complex rounding. For fixed
a device offset use --offset data device offset use --offset
option instead. option instead.
--uuid=UUID --uuid=UUID
Use the provided UUID for the luksFormat command instead of g enerating a new one. Changes the Use the provided UUID for the luksFormat command instead of genera ting a new one. Changes the
existing UUID when used with the luksUUID command. existing UUID when used with the luksUUID command.
The UUID must be provided in the standard UUID format, e.g. 123456 78-1234-1234-1234-123456789abc. The UUID must be provided in the standard UUID format, e.g. 123456 78-1234-1234-1234-123456789abc.
--allow-discards --allow-discards
Allow the use of discard (TRIM) requests for the device. This opt ion is only relevant for open Allow the use of discard (TRIM) requests for the device. This option is only relevant for open
action. This is also not supported for LUKS2 devices with data in tegrity protection. action. This is also not supported for LUKS2 devices with data in tegrity protection.
WARNING: This command can have a negative security impact beca WARNING: This command can have a negative security impact because
use it can make filesystem-level it can make filesystem-level
operations visible on the physical device. For example, informatio operations visible on the physical device. For example, informati
n leaking filesystem type, used on leaking filesystem type, used
space, etc. may be extractable from the physical device if the space, etc. may be extractable from the physical device if the dis
discarded blocks can be located carded blocks can be located
later. If in doubt, do not use it. later. If in doubt, do not use it.
A kernel version of 3.1 or later is needed. For earlier kernels, t his option is ignored. A kernel version of 3.1 or later is needed. For earlier kernels, t his option is ignored.
--perf-same_cpu_crypt --perf-same_cpu_crypt
Perform encryption using the same cpu that IO was submitted on. T Perform encryption using the same cpu that IO was submitted on.
he default is to use an unbound The default is to use an unbound
workqueue so that encryption work is automatically balanced betw workqueue so that encryption work is automatically balanced betwee
een available CPUs. This option n available CPUs. This option
is only relevant for open action. is only relevant for open action.
NOTE: This option is available only for low-level dm-crypt perform ance tuning, use only if you NOTE: This option is available only for low-level dm-crypt per formance tuning, use only if you
need a change to default dm-crypt behaviour. Needs kernel 4.0 or l ater. need a change to default dm-crypt behaviour. Needs kernel 4.0 or l ater.
--perf-submit_from_crypt_cpus --perf-submit_from_crypt_cpus
Disable offloading writes to a separate thread after encryption. There are some situations where Disable offloading writes to a separate thread after encryption. There are some situations where
offloading write bios from the encryption threads to a single thre ad degrades performance signifi- offloading write bios from the encryption threads to a single thre ad degrades performance signifi-
cantly. The default is to offload write bios to the same threa d. This option is only relevant cantly. The default is to offload write bios to the same thread. This option is only relevant
for open action. for open action.
NOTE: This option is available only for low-level dm-crypt perform ance tuning, use only if you NOTE: This option is available only for low-level dm-crypt per formance tuning, use only if you
need a change to default dm-crypt behaviour. Needs kernel 4.0 or l ater. need a change to default dm-crypt behaviour. Needs kernel 4.0 or l ater.
--perf-no_read_workqueue, --perf-no_write_workqueue --perf-no_read_workqueue, --perf-no_write_workqueue
Bypass dm-crypt internal workqueue and process read or write requ ests synchronously. This option Bypass dm-crypt internal workqueue and process read or write reque sts synchronously. This option
is only relevant for open action. is only relevant for open action.
NOTE: These options are available only for low-level dm-crypt perf ormance tuning, use only if you NOTE: These options are available only for low-level dm-crypt per formance tuning, use only if you
need a change to default dm-crypt behaviour. Needs kernel 5.9 or l ater. need a change to default dm-crypt behaviour. Needs kernel 5.9 or l ater.
--test-passphrase --test-passphrase
Do not activate the device, just verify passphrase. This option is only relevant for open action Do not activate the device, just verify passphrase. This option i s only relevant for open action
(the device mapping name is not mandatory if this option is used). (the device mapping name is not mandatory if this option is used).
--header <device or file storing the LUKS header> --header <device or file storing the LUKS header>
Use a detached (separated) metadata device or file where the LUKS header is stored. This option Use a detached (separated) metadata device or file where the LU KS header is stored. This option
allows one to store ciphertext and LUKS header on different device s. allows one to store ciphertext and LUKS header on different device s.
This option is only relevant for LUKS devices and can be used wit h the luksFormat, open, luksSus- This option is only relevant for LUKS devices and can be used with the luksFormat, open, luksSus-
pend, luksResume, status and resize commands. pend, luksResume, status and resize commands.
For luksFormat with a file name as the argument to --header, the f ile will be automatically cre- For luksFormat with a file name as the argument to --header, the file will be automatically cre-
ated if it does not exist. See the cryptsetup FAQ for header size calculation. ated if it does not exist. See the cryptsetup FAQ for header size calculation.
For other commands that change the LUKS header (e.g. luksAddKey), specify the device or file with For other commands that change the LUKS header (e.g. luksAddKey), specify the device or file with
the LUKS header directly as the LUKS device. the LUKS header directly as the LUKS device.
If used with luksFormat, the --align-payload option is taken as absolute sector alignment on If used with luksFormat, the --align-payload option is taken as absolute sector alignment on
ciphertext device and can be zero. ciphertext device and can be zero.
WARNING: There is no check whether the ciphertext device specifie WARNING: There is no check whether the ciphertext device specified
d actually belongs to the header actually belongs to the header
given. In fact, you can specify an arbitrary device as the ciphert given. In fact, you can specify an arbitrary device as the cip
ext device for open with the hertext device for open with the
--header option. Use with care. --header option. Use with care.
--header-backup-file <file> --header-backup-file <file>
Specify file with header backup for luksHeaderBackup or luksHeader Restore actions. Specify file with header backup for luksHeaderBackup or luksHeader Restore actions.
--force-password --force-password
Do not use password quality checking for new LUKS passwords. Do not use password quality checking for new LUKS passwords.
This option applies only to luksFormat, luksAddKey and luksChange Key and is ignored if cryptsetup This option applies only to luksFormat, luksAddKey and luksChangeK ey and is ignored if cryptsetup
is built without password quality checking support. is built without password quality checking support.
For more info about password quality check, see the manual page fo r pwquality.conf(5) and pass- For more info about password quality check, see the manual page for pwquality.conf(5) and pass-
wdqc.conf(5). wdqc.conf(5).
--deferred --deferred
Defers device removal in close command until the last user closes it. Defers device removal in close command until the last user closes it.
--cancel-deferred
Removes a previously configured deferred device removal in close c
ommand.
--disable-external-tokens
Disable loading of plugins for external LUKS2 tokens.
--disable-locks --disable-locks
Disable lock protection for metadata on disk. This option is vali d only for LUKS2 and ignored for Disable lock protection for metadata on disk. This option is vali d only for LUKS2 and ignored for
other formats. other formats.
WARNING: Do not use this option unless you run cryptsetup in a res tricted environment where lock- WARNING: Do not use this option unless you run cryptsetup in a re stricted environment where lock-
ing is impossible to perform (where /run directory cannot be used) . ing is impossible to perform (where /run directory cannot be used) .
--disable-keyring --disable-keyring
Do not load volume key in kernel keyring and store it directly in the dm-crypt target instead. Do not load volume key in kernel keyring and store it directly in the dm-crypt target instead.
This option is supported only for the LUKS2 format. This option is supported only for the LUKS2 format.
--key-description <text> --key-description <text>
Set key description in keyring for use with token command. Set key description in keyring for use with token command.
--priority <normal|prefer|ignore> --priority <normal|prefer|ignore>
Set a priority for LUKS2 keyslot. The prefer priority marked slot s are tried before normal prior- Set a priority for LUKS2 keyslot. The prefer priority marked slot s are tried before normal prior-
ity. The ignored priority means, that slot is never used , if not explicitly requested by ity. The ignored priority means, that slot is never used, if not explicitly requested by
--key-slot option. --key-slot option.
--token-id --token-id
Specify what token to use in actions token, open or resize. If om itted, all available tokens will Specify what token to use in actions token, open or resize. If om itted, all available tokens will
be checked before proceeding further with passphrase prompt. be checked before proceeding further with passphrase prompt.
--token-only --token-only
Do not proceed further with action (any of token, open or res ize) if token activation failed. Do not proceed further with action (any of token, open or resize) if token activation failed.
Without the option, action asks for passphrase to proceed further. Without the option, action asks for passphrase to proceed further.
--token-type
Restrict tokens eligible for operation to specific token ty
pe (name). Mostly useful when no
--token-id is specified.
--sector-size <bytes> --sector-size <bytes>
Set sector size for use with disk encryption. It must be power of two and in range 512 - 4096 Set sector size for use with disk encryption. It must be power of two and in range 512 - 4096
bytes. The default is 512 bytes sectors. This option is available bytes. This option is available only in the LUKS2 or plain modes.
only in the LUKS2 mode.
The default for plain mode is 512 bytes. For LUKS2 devices it
's established during luksFormat
operation based on parameters provided by underlying data device.
For native 4K block devices
it's 4096 bytes. For 4K/512e (4K physical sector size with 512 b
ytes emulation) it's 4096 bytes.
For drives reporting only 512 bytes block size it remains 512 byte
s. If data device is regular
file put in filesystem it's 4096 bytes.
Note that if sector size is higher than underlying device hardware sector and there is not Note that if sector size is higher than underlying device hardware sector and there is not
integrity protection that uses data journal, using this option can increase risk on incomplete integrity protection that uses data journal, using this option can increase risk on incomplete
sector writes during a power fail. sector writes during a power fail.
If used together with --integrity option and dm-integrity jou rnal, the atomicity of writes is If used together with --integrity option and dm-integrity jou rnal, the atomicity of writes is
guaranteed in all cases (but it cost write performance - data has to be written twice). guaranteed in all cases (but it cost write performance - data has to be written twice).
Increasing sector size from 512 bytes to 4096 bytes can provide be tter performance on most of the Increasing sector size from 512 bytes to 4096 bytes can provide be tter performance on most of the
modern storage devices and also with some hw encryption accelerato rs. modern storage devices and also with some hw encryption accelerato rs.
skipping to change at line 1121 skipping to change at line 1167
--unbound --unbound
Creates new or dumps existing LUKS2 unbound keyslot. See luksAddKe y or luksDump actions for more Creates new or dumps existing LUKS2 unbound keyslot. See luksAddKe y or luksDump actions for more
details. details.
--tcrypt-hidden --tcrypt-hidden
--tcrypt-system --tcrypt-backup Specify which TrueCrypt on-disk header will be used to open the --tcrypt-system --tcrypt-backup Specify which TrueCrypt on-disk header will be used to open the
device. See TCRYPT section for more info. device. See TCRYPT section for more info.
--veracrypt --veracrypt
Allow VeraCrypt compatible mode. Only for TCRYPT extension. See T This option is ignored as VeraCrypt compatible mode is supported b
CRYPT section for more info. y default.
--disable-veracrypt
This option can be used to disable VeraCrypt compatible mode (only
TrueCrypt devices are recog-
nized). Only for TCRYPT extension. See TCRYPT section for more inf
o.
--veracrypt-pim --veracrypt-pim
--veracrypt-query-pim Use a custom Personal Iteration Multiplier ( PIM) for VeraCrypt device. See --veracrypt-query-pim Use a custom Personal Iteration Multiplier (PIM) for VeraCrypt device. See
TCRYPT section for more info. TCRYPT section for more info.
--serialize-memory-hard-pbkdf --serialize-memory-hard-pbkdf
Use a global lock to serialize unlocking of keyslots using memory- hard PBKDF. Use a global lock to serialize unlocking of keyslots using memory- hard PBKDF.
NOTE: This is (ugly) workaround for a specific situation when m ultiple devices are activated in NOTE: This is (ugly) workaround for a specific situation when mult iple devices are activated in
parallel and system instead of reporting out of memory starts unco nditionally stop processes using parallel and system instead of reporting out of memory starts unco nditionally stop processes using
out-of-memory killer. out-of-memory killer.
DO NOT USE this switch until you are implementing boot environme nt with parallel devices activa- DO NOT USE this switch until you are implementing boot environment with parallel devices activa-
tion! tion!
--encrypt --encrypt
Initialize (and run) device encryption (reencrypt action parameter ) Initialize (and run) device encryption (reencrypt action parameter )
--decrypt --decrypt
Initialize (and run) device decryption (reencrypt action parameter ) Initialize (and run) device decryption (reencrypt action parameter )
--init-only --init-only
Initialize reencryption (any variant) operation in LUKS2 metadata only and exit. If any reencrypt Initialize reencryption (any variant) operation in LUKS2 metadata only and exit. If any reencrypt
operation is already initialized in metadata, the command with --i nit-only parameter fails. operation is already initialized in metadata, the command with --i nit-only parameter fails.
--resume-only --resume-only
Resume reencryption (any variant) operation already described in Resume reencryption (any variant) operation already described in L
LUKS2 metadata. If no reencrypt UKS2 metadata. If no reencrypt
operation is initialized, the command with --resume-only paramete operation is initialized, the command with --resume-only para
r fails. Useful for resuming meter fails. Useful for resuming
reencrypt operation without accidentally triggering new reencrypti on operation. reencrypt operation without accidentally triggering new reencrypti on operation.
--resilience <mode> --resilience <mode>
Reencryption resilience mode can be one of checksum, journal or no ne. Reencryption resilience mode can be one of checksum, journal or no ne.
checksum: default mode, where individual checksums of ciphertex checksum: default mode, where individual checksums of ciphertext h
t hotzone sectors are stored, so otzone sectors are stored, so
the recovery process can detect which sectors where already reencr the recovery process can detect which sectors were already re
ypted. It requires that the encrypted. It requires that the
device sector write is atomic. device sector write is atomic.
journal: the hotzone is journaled in the binary area (so the data are written twice). journal: the hotzone is journaled in the binary area (so the data are written twice).
none: performance mode. There is no protection and the only way it's safe to interrupt the reen- none: performance mode. There is no protection and the only way it 's safe to interrupt the reen-
cryption is similar to old offline reencryption utility. (ctrl+c). cryption is similar to old offline reencryption utility. (ctrl+c).
The option is ignored if reencryption with datashift mode is in pr ogress. The option is ignored if reencryption with datashift mode is in pr ogress.
--resilience-hash <hash> --resilience-hash <hash>
The hash algorithm used with "--resilience checksum" only. The de fault hash is sha256. With other The hash algorithm used with "--resilience checksum" only. The de fault hash is sha256. With other
resilience modes, the hash parameter is ignored. resilience modes, the hash parameter is ignored.
--hotzone-size <size> --hotzone-size <size>
This option can be used to set an upper limit on the size of r This option can be used to set an upper limit on the size of reen
eencryption area (hotzone). The cryption area (hotzone). The
<size> can be specified with unit suffix (for example 50M). Note t <size> can be specified with unit suffix (for example 50M). Note
hat actual hotzone size may be that actual hotzone size may be
less than specified <size> due to other limitations (free space in keyslots area or available mem- less than specified <size> due to other limitations (free space in keyslots area or available mem-
ory). ory).
--reduce-device-size <size> --reduce-device-size <size>
Initialize LUKS2 reencryption with data device size reduction (cur rently only --encrypt variant is Initialize LUKS2 reencryption with data device size reduction (cur rently only --encrypt variant is
supported). supported).
Last <size> sectors of <device> will be used to properly initi alize device reencryption. That Last <size> sectors of <device> will be used to properly initiali ze device reencryption. That
means any data at last <size> sectors will be lost. means any data at last <size> sectors will be lost.
It could be useful if you added some space to underlying partition or logical volume (so last It could be useful if you added some space to underlying part ition or logical volume (so last
<size> sectors contains no data). <size> sectors contains no data).
Recommended minimal size is twice the default LUKS2 header siz e (--reduce-device-size 32M) for Recommended minimal size is twice the default LUKS2 header size (--reduce-device-size 32M) for
--encrypt use case. Be sure to have enough (at least --reduce-devi ce-size value of free space --encrypt use case. Be sure to have enough (at least --reduce-devi ce-size value of free space
at the end of <device>). at the end of <device>).
WARNING: This is a destructive operation and cannot be reverted. Use with extreme care - acciden- WARNING: This is a destructive operation and cannot be reverted. Use with extreme care - acciden-
tally overwritten filesystems are usually unrecoverable. tally overwritten filesystems are usually unrecoverable.
--version --version
Show the program version. Show the program version.
--usage --usage
skipping to change at line 1227 skipping to change at line 1277
Example 5: Erase all key slots on /dev/sdX. Example 5: Erase all key slots on /dev/sdX.
sudo cryptsetup erase /dev/sdX sudo cryptsetup erase /dev/sdX
Example 6: Restore LUKS header from backup file. Example 6: Restore LUKS header from backup file.
sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /v ar/tmp/NameOfBackupFile sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /v ar/tmp/NameOfBackupFile
RETURN CODES RETURN CODES
Cryptsetup returns 0 on success and a non-zero value on error. Cryptsetup returns 0 on success and a non-zero value on error.
Error codes are: 1 wrong parameters, 2 no permission (bad passphrase), 3 out of memory, 4 wrong device Error codes are: 1 wrong parameters, 2 no permission (bad passphrase), 3 out of memory, 4 wrong device
specified, 5 device already exists or device is busy. specified, 5 device already exists or device is busy.
NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE
Note that no iterated hashing or salting is done in plain mode. If hashing is done, it is a single Note that no iterated hashing or salting is done in plain mode. If hashi ng is done, it is a single
direct hash. This means that low-entropy passphrases are easy to attack i n plain mode. direct hash. This means that low-entropy passphrases are easy to attack i n plain mode.
From a terminal: The passphrase is read until the first newline, i.e. '\n From a terminal: The passphrase is read until the first newline, i.e. '
'. The input without the new- \n'. The input without the new-
line character is processed with the default hash or the hash specifi line character is processed with the default hash or the hash specified w
ed with --hash. The hash result ith --hash. The hash result
will be truncated to the key size of the used cipher, or the size specifi ed with -s. will be truncated to the key size of the used cipher, or the size specifi ed with -s.
From stdin: Reading will continue until a newline (or until the maximum i From stdin: Reading will continue until a newline (or until the maximum
nput size is reached), with the input size is reached), with the
trailing newline stripped. The maximum input size is defined by the sam trailing newline stripped. The maximum input size is defined by the same
e compiled-in default as for the compiled-in default as for the
maximum key file size and can be overwritten using --keyfile-size option. maximum key file size and can be overwritten using --keyfile-size option.
The data read will be hashed with the default hash or the hash specified with --hash. The hash result The data read will be hashed with the default hash or the hash specifi ed with --hash. The hash result
will be truncated to the key size of the used cipher, or the size specifi ed with -s. will be truncated to the key size of the used cipher, or the size specifi ed with -s.
Note that if --key-file=- is used for reading the key from stdin, trailin g newlines are not stripped from Note that if --key-file=- is used for reading the key from stdin, trailin g newlines are not stripped from
the input. the input.
If "plain" is used as argument to --hash, the input data will not be hash ed. Instead, it will be zero If "plain" is used as argument to --hash, the input data will not be hashed. Instead, it will be zero
padded (if shorter than the key size) or truncated (if longer than the ke y size) and used directly as the padded (if shorter than the key size) or truncated (if longer than the ke y size) and used directly as the
binary key. This is useful for directly specifying a binary key. No warn ing will be given if the amount binary key. This is useful for directly specifying a binary key. No war ning will be given if the amount
of data read from stdin is less than the key size. of data read from stdin is less than the key size.
From a key file: It will be truncated to the key size of the used ci pher or the size given by -s and From a key file: It will be truncated to the key size of the used cipher or the size given by -s and
directly used as a binary key. directly used as a binary key.
WARNING: The --hash argument is being ignored. The --hash option is usab le only for stdin input in plain WARNING: The --hash argument is being ignored. The --hash option is usab le only for stdin input in plain
mode. mode.
If the key file is shorter than the key, cryptsetup will quit with an e If the key file is shorter than the key, cryptsetup will quit with an err
rror. The maximum input size is or. The maximum input size is
defined by the same compiled-in default as for the maximum key file size defined by the same compiled-in default as for the maximum key file s
and can be overwritten using ize and can be overwritten using
--keyfile-size option. --keyfile-size option.
NOTES ON PASSPHRASE PROCESSING FOR LUKS NOTES ON PASSPHRASE PROCESSING FOR LUKS
LUKS uses PBKDF2 to protect against dictionary attacks and to giv e some protection to low-entropy LUKS uses PBKDF2 to protect against dictionary attacks and to give s ome protection to low-entropy
passphrases (see RFC 2898 and the cryptsetup FAQ). passphrases (see RFC 2898 and the cryptsetup FAQ).
From a terminal: The passphrase is read until the first newline and then processed by PBKDF2 without the From a terminal: The passphrase is read until the first newline and then processed by PBKDF2 without the
newline character. newline character.
From stdin: LUKS will read passphrases from stdin up to the first newl ine character or the compiled-in From stdin: LUKS will read passphrases from stdin up to the first newline character or the compiled-in
maximum key file length. If --keyfile-size is given, it is ignored. maximum key file length. If --keyfile-size is given, it is ignored.
From key file: The complete keyfile is read up to the compiled-in maximum size. Newline characters do not From key file: The complete keyfile is read up to the compiled-in maximum size. Newline characters do not
terminate the input. The --keyfile-size option can be used to limit what is read. terminate the input. The --keyfile-size option can be used to limit what is read.
Passphrase processing: Whenever a passphrase is added to a LUKS header (l uksAddKey, luksFormat), the user Passphrase processing: Whenever a passphrase is added to a LUKS header (l uksAddKey, luksFormat), the user
may specify how much the time the passphrase processing should consume. T he time is used to determine the may specify how much the time the passphrase processing should consume. T he time is used to determine the
iteration count for PBKDF2 and higher times will offer better protection for low-entropy passphrases, but iteration count for PBKDF2 and higher times will offer better protection for low-entropy passphrases, but
open will take longer to complete. For passphrases that have entropy high er than the used key length, open will take longer to complete. For passphrases that have entropy higher than the used key length,
higher iteration times will not increase security. higher iteration times will not increase security.
The default setting of one or two seconds is sufficient for most practica l cases. The only exception is a The default setting of one or two seconds is sufficient for most practica l cases. The only exception is a
low-entropy passphrase used on a device with a slow CPU, as this will res ult in a low iteration count. On low-entropy passphrase used on a device with a slow CPU, as this will res ult in a low iteration count. On
a slow device, it may be advisable to increase the iteration time using the --iter-time option in order a slow device, it may be advisable to increase the iteration time using t he --iter-time option in order
to obtain a higher iteration count. This does slow down all later luksOpe n operations accordingly. to obtain a higher iteration count. This does slow down all later luksOpe n operations accordingly.
INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS
LUKS checks for a valid passphrase when an encrypted partition is unlocke LUKS checks for a valid passphrase when an encrypted partition is unl
d. The behavior of plain dm- ocked. The behavior of plain dm-
crypt is different. It will always decrypt with the passphrase given. I crypt is different. It will always decrypt with the passphrase given. If
f the given passphrase is wrong, the given passphrase is wrong,
the device mapped by plain dm-crypt will essentially still contain encryp ted data and will be unreadable. the device mapped by plain dm-crypt will essentially still contain encryp ted data and will be unreadable.
NOTES ON SUPPORTED CIPHERS, MODES, HASHES AND KEY SIZES NOTES ON SUPPORTED CIPHERS, MODES, HASHES AND KEY SIZES
The available combinations of ciphers, modes, hashes and key sizes d The available combinations of ciphers, modes, hashes and key siz
epend on kernel support. See es depend on kernel support. See
/proc/crypto for a list of available options. You might need to load add /proc/crypto for a list of available options. You might need to load addi
itional kernel crypto modules in tional kernel crypto modules in
order to get more options. order to get more options.
For the --hash option, if the crypto backend is libgcrypt, then all algor ithms supported by the gcrypt For the --hash option, if the crypto backend is libgcrypt, then all al gorithms supported by the gcrypt
library are available. For other crypto backends, some algorithms may be missing. library are available. For other crypto backends, some algorithms may be missing.
NOTES ON PASSPHRASES NOTES ON PASSPHRASES
Mathematics can't be bribed. Make sure you keep your passphrases safe. There are a few nice tricks for Mathematics can't be bribed. Make sure you keep your passphrases safe. T here are a few nice tricks for
constructing a fallback, when suddenly out of the blue, your brain refuse s to cooperate. These fallbacks constructing a fallback, when suddenly out of the blue, your brain refuse s to cooperate. These fallbacks
need LUKS, as it's only possible with LUKS to have multiple passphrase s. Still, if your attacker model need LUKS, as it's only possible with LUKS to have multiple passphrases. Still, if your attacker model
does not prevent it, storing your passphrase in a sealed envelope somewhe re may be a good idea as well. does not prevent it, storing your passphrase in a sealed envelope somewhe re may be a good idea as well.
NOTES ON RANDOM NUMBER GENERATORS NOTES ON RANDOM NUMBER GENERATORS
Random Number Generators (RNG) used in cryptsetup are always the kernel R NGs without any modifications or Random Number Generators (RNG) used in cryptsetup are always the kernel R NGs without any modifications or
additions to data stream produced. additions to data stream produced.
There are two types of randomness cryptsetup/LUKS needs. One type (wh ich always uses /dev/urandom) is There are two types of randomness cryptsetup/LUKS needs. One type (which always uses /dev/urandom) is
used for salts, the AF splitter and for wiping deleted keyslots. used for salts, the AF splitter and for wiping deleted keyslots.
The second type is used for the volume (master) key. You can switch The second type is used for the volume (master) key. You can swit
between using /dev/random and ch between using /dev/random and
/dev/urandom here, see --use-random and --use-urandom options. Using /dev/urandom here, see --use-random and --use-urandom options. Using /de
/dev/random on a system without v/random on a system without
enough entropy sources can cause luksFormat to block until the requested enough entropy sources can cause luksFormat to block until the requeste
amount of random data is gath- d amount of random data is gath-
ered. In a low-entropy situation (embedded system), this can take a ver ered. In a low-entropy situation (embedded system), this can take a very
y long time and potentially for- long time and potentially for-
ever. At the same time, using /dev/urandom in a low-entropy situation wil l produce low-quality keys. This ever. At the same time, using /dev/urandom in a low-entropy situation wil l produce low-quality keys. This
is a serious problem, but solving it is out of scope for a mere man-page. See urandom(4) for more infor- is a serious problem, but solving it is out of scope for a mere man-page. See urandom(4) for more infor-
mation. mation.
AUTHENTICATED DISK ENCRYPTION (EXPERIMENTAL) AUTHENTICATED DISK ENCRYPTION (EXPERIMENTAL)
Since Linux kernel version 4.12 dm-crypt supports authenticated disk encr yption. Since Linux kernel version 4.12 dm-crypt supports authenticated disk encr yption.
Normal disk encryption modes are length-preserving (plaintext sector is o Normal disk encryption modes are length-preserving (plaintext sector is
f the same size as a ciphertext of the same size as a ciphertext
sector) and can provide only confidentiality protection, but not crypto sector) and can provide only confidentiality protection, but not cryptogr
graphically sound data integrity aphically sound data integrity
protection. protection.
Authenticated modes require additional space per-sector for authenticati on tag and use Authenticated Authenticated modes require additional space per-sector for authenti cation tag and use Authenticated
Encryption with Additional Data (AEAD) algorithms. Encryption with Additional Data (AEAD) algorithms.
If you configure LUKS2 device with data integrity protection, there wi If you configure LUKS2 device with data integrity protection, there will
ll be an underlying dm-integrity be an underlying dm-integrity
device, which provides additional per-sector metadata space and also prov device, which provides additional per-sector metadata space and also pr
ide data journal protection to ovide data journal protection to
ensure atomicity of data and metadata update. Because there must be a ensure atomicity of data and metadata update. Because there must be addi
dditional space for metadata and tional space for metadata and
journal, the available space for the device will be smaller than for leng th-preserving modes. journal, the available space for the device will be smaller than for leng th-preserving modes.
The dm-crypt device then resides on top of such a dm-integrity device. A The dm-crypt device then resides on top of such a dm-integrity device.
ll activation and deactivation All activation and deactivation
of this device stack is performed by cryptsetup, there is no difference of this device stack is performed by cryptsetup, there is no difference i
in using luksOpen for integrity n using luksOpen for integrity
protected devices. If you want to format LUKS2 device with data integrit protected devices. If you want to format LUKS2 device with data integ
y protection, use --integrity rity protection, use --integrity
option. option.
Since dm-integrity doesn't support discards (TRIM), dm-crypt devic e on top of it inherits this, so Since dm-integrity doesn't support discards (TRIM), dm-crypt device on top of it inherits this, so
integrity protection mode doesn't support discards either. integrity protection mode doesn't support discards either.
Some integrity modes requires two independent keys (key for encryption and for authentication). Both Some integrity modes requires two independent keys (key for encrypti on and for authentication). Both
these keys are stored in one LUKS keyslot. these keys are stored in one LUKS keyslot.
WARNING: All support for authenticated modes is experimental and there a WARNING: All support for authenticated modes is experimental and there ar
re only some modes available for e only some modes available for
now. Note that there are a very few authenticated encryption algorithms now. Note that there are a very few authenticated encryption algor
that are suitable for disk ithms that are suitable for disk
encryption. You also cannot use CRC32 or any other non-cryptographic c encryption. You also cannot use CRC32 or any other non-cryptographic chec
hecksums (other than the special ksums (other than the special
integrity mode "none"). If for some reason you want to have integrity con integrity mode "none"). If for some reason you want to have integrity c
trol without using authentica- ontrol without using authentica-
tion mode, then you should separately configure dm-integrity independentl y of LUKS2. tion mode, then you should separately configure dm-integrity independentl y of LUKS2.
NOTES ON LOOPBACK DEVICE USE NOTES ON LOOPBACK DEVICE USE
Cryptsetup is usually used directly on a block device (disk partition or LVM volume). However, if the Cryptsetup is usually used directly on a block device (disk partition or LVM volume). However, if the
device argument is a file, cryptsetup tries to allocate a loopback device and map it into this file. This device argument is a file, cryptsetup tries to allocate a loopback device and map it into this file. This
mode requires Linux kernel 2.6.25 or more recent which supports the loo p autoclear flag (loop device is mode requires Linux kernel 2.6.25 or more recent which supports the loop autoclear flag (loop device is
cleared on the last close automatically). Of course, you can always map a file to a loop-device manually. cleared on the last close automatically). Of course, you can always map a file to a loop-device manually.
See the cryptsetup FAQ for an example. See the cryptsetup FAQ for an example.
When device mapping is active, you can see the loop backing file in the status command output. Also see When device mapping is active, you can see the loop backing file in the s tatus command output. Also see
losetup(8). losetup(8).
LUKS2 header locking LUKS2 header locking
The LUKS2 on-disk metadata is updated in several steps and to achieve pro The LUKS2 on-disk metadata is updated in several steps and to achieve
per atomic update, there is a proper atomic update, there is a
locking mechanism. For an image in file, code uses flock(2) system ca locking mechanism. For an image in file, code uses flock(2) system call.
ll. For a block device, lock is For a block device, lock is
performed over a special file stored in a locking directory (by default / run/lock/cryptsetup). The lock- performed over a special file stored in a locking directory (by default / run/lock/cryptsetup). The lock-
ing directory should be created with the proper security context by the distribution during the boot-up ing directory should be created with the proper security context by the d istribution during the boot-up
phase. Only LUKS2 uses locks, other formats do not use this mechanism. phase. Only LUKS2 uses locks, other formats do not use this mechanism.
DEPRECATED ACTIONS DEPRECATED ACTIONS
The reload action is no longer supported. Please use dmsetup(8) if you n eed to directly manipulate with The reload action is no longer supported. Please use dmsetup(8) if you need to directly manipulate with
the device mapping table. the device mapping table.
The luksDelKey was replaced with luksKillSlot. The luksDelKey was replaced with luksKillSlot.
REPORTING BUGS REPORTING BUGS
Report bugs, including ones in the documentation, on the cryptsetup mai Report bugs, including ones in the documentation, on the cryptsetup maili
ling list at <dm-crypt@saout.de> ng list at <dm-crypt@saout.de>
or in the 'Issues' section on LUKS website. Please attach the output of or in the 'Issues' section on LUKS website. Please attach the outpu
the failed command with the t of the failed command with the
--debug option added. --debug option added.
AUTHORS AUTHORS
cryptsetup originally written by Jana Saout <jana@saout.de> cryptsetup originally written by Jana Saout <jana@saout.de>
The LUKS extensions and original man page were written by Clemens Fruhwir th <clemens@endorphin.org>. The LUKS extensions and original man page were written by Clemens Fruhwir th <clemens@endorphin.org>.
Man page extensions by Milan Broz <gmazyland@gmail.com>. Man page extensions by Milan Broz <gmazyland@gmail.com>.
Man page rewrite and extension by Arno Wagner <arno@wagner.name>. Man page rewrite and extension by Arno Wagner <arno@wagner.name>.
COPYRIGHT COPYRIGHT
Copyright © 2004 Jana Saout Copyright © 2004 Jana Saout
Copyright © 2004-2006 Clemens Fruhwirth Copyright © 2004-2006 Clemens Fruhwirth
Copyright © 2012-2014 Arno Wagner Copyright © 2012-2014 Arno Wagner
Copyright © 2009-2021 Red Hat, Inc. Copyright © 2009-2021 Red Hat, Inc.
Copyright © 2009-2021 Milan Broz Copyright © 2009-2021 Milan Broz
This is free software; see the source for copying conditions. There i s NO warranty; not even for MER- This is free software; see the source for copying conditions. There is N O warranty; not even for MER-
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SEE ALSO SEE ALSO
The LUKS website at https://gitlab.com/cryptsetup/cryptsetup/ The LUKS website at https://gitlab.com/cryptsetup/cryptsetup/
The cryptsetup FAQ, contained in the distribution package and onlin e at https://gitlab.com/crypt- The cryptsetup FAQ, contained in the distribution package and onl ine at https://gitlab.com/crypt-
setup/cryptsetup/wikis/FrequentlyAskedQuestions setup/cryptsetup/wikis/FrequentlyAskedQuestions
The cryptsetup mailing list and list archive, see FAQ entry 1.6. The cryptsetup mailing list and list archive, see FAQ entry 1.6.
The LUKS version 1 on-disk format specification available at http s://gitlab.com/cryptsetup/crypt- The LUKS version 1 on-disk format specification available at http s://gitlab.com/cryptsetup/crypt-
setup/wikis/Specification and LUKS version 2 at https://gitlab.com/crypts etup/LUKS2-docs. setup/wikis/Specification and LUKS version 2 at https://gitlab.com/crypts etup/LUKS2-docs.
cryptsetup January 2021 CRYPTSETUP(8) cryptsetup January 2021 CRYPTSETUP(8)
 End of changes. 160 change blocks. 
370 lines changed or deleted 441 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)