1CRYPTSETUP(8)                Maintenance Commands                CRYPTSETUP(8)


6       cryptsetup - manage plain dm-crypt and LUKS encrypted volumes


9       cryptsetup <options> <action> <action args>


12       cryptsetup is used to conveniently setup dm-crypt managed device-mapper
13       mappings. These include plain dm-crypt volumes and  LUKS  volumes.  The
14       difference is that LUKS uses a metadata header and can hence offer more
15       features than plain dm-crypt. On the other hand, the header is  visible
16       and vulnerable to damage.
18       In  addition,  cryptsetup provides limited support for the use of loop-
19       AES volumes and for TrueCrypt compatible volumes.


23       Unless you understand the  cryptographic  background  well,  use  LUKS.
24       With  plain  dm-crypt  there  are a number of possible user errors that
25       massively decrease security. While LUKS cannot fix  them  all,  it  can
26       lessen the impact for many of them.


29       A  lot  of good information on the risks of using encrypted storage, on
30       handling problems and on security aspects can be found  in  the  Crypt‐
31       setup  FAQ.  Read  it.  Nonetheless, some risks deserve to be mentioned
32       here.
34       Backup: Storage media die. Encryption has no influence on that.  Backup
35       is mandatory for encrypted data as well, if the data has any worth. See
36       the Cryptsetup FAQ for advice on how to do a  backup  of  an  encrypted
37       volume.
39       Character encoding: If you enter a passphrase with special symbols, the
40       passphrase can change depending on character  encoding.  Keyboard  set‐
41       tings  can  also change, which can make blind input hard or impossible.
42       For example, switching from some ASCII 8-bit variant to UTF-8 can  lead
43       to  a  different binary encoding and hence different passphrase seen by
44       cryptsetup, even if what you see on the terminal is exactly  the  same.
45       It is therefore highly recommended to select passphrase characters only
46       from 7-bit ASCII, as the encoding for 7-bit ASCII stays  the  same  for
47       all ASCII variants and UTF-8.
49       LUKS  header:  If the header of a LUKS volume gets damaged, all data is
50       permanently lost unless you have a header-backup.   If  a  key-slot  is
51       damaged,  it  can  only  be restored from a header-backup or if another
52       active key-slot with known passphrase is undamaged.  Damaging the  LUKS
53       header is something people manage to do with surprising frequency. This
54       risk is the result of a trade-off between security and safety, as  LUKS
55       is  designed  for fast and secure wiping by just overwriting header and
56       key-slot area.
58       Previously used partitions: If a partition was previously used, it is a
59       very  good idea to wipe filesystem signatures, data, etc. before creat‐
60       ing a LUKS or plain dm-crypt container on it.  For a quick  removal  of
61       filesystem signatures, use "wipefs". Take care though that this may not
62       remove everything. In particular, MD RAID signatures at the  end  of  a
63       device  may  survive.  It  also  does not remove data. For a full wipe,
64       overwrite the whole partition before container creation. If you do  not
65       know how to do that, the cryptsetup FAQ describes several options.


69       The following are valid actions for all supported device types.
71       open <device> <name> --type <device_type>
73              Opens (creates a mapping with) <name> backed by device <device>.
75              Device  type can be plain, luks (default), luks1, luks2, loopaes
76              or tcrypt.
78              For backward compatibility there are open command aliases:
80              create (argument-order <name> <device>): open --type plain
81              plainOpen: open --type plain
82              luksOpen: open --type luks
83              loopaesOpen: open --type loopaes
84              tcryptOpen: open --type tcrypt
86              <options> are type specific and are described below for individ‐
87              ual  device  types.  For  create,  the  order  of the <name> and
88              <device> options is inverted for historical reasons,  all  other
89              aliases use the standard <device> <name> order.
91       close <name>
93              Removes  the existing mapping <name> and wipes the key from ker‐
94              nel memory.
96              For backward compatibility  there  are  close  command  aliases:
97              remove,  plainClose,  luksClose,  loopaesClose, tcryptClose (all
98              behaves exactly the same, device type  is  determined  automati‐
99              cally from active device).
101              <options> can be [--deferred]
104       status <name>
106              Reports the status for the mapping <name>.
108       resize <name>
110              Resizes an active mapping <name>.
112              If --size (in 512-bytes sectors) or --device-size are not speci‐
113              fied, the size is computed from the underlying device. For  LUKS
114              it  is  the  size  of  the  underlying  device  without the area
115              reserved for LUKS header (see data payload  offset  in  luksDump
116              command).   For  plain  crypt  device,  the whole device size is
117              used.
119              Note that this does not change the raw device geometry, it  just
120              changes  how  many  sectors of the raw device are represented in
121              the mapped device.
123              If cryptsetup detected volume key for active  device  loaded  in
124              kernel  keyring  service,  resize  action  would  first  try  to
125              retrieve the key using a token and only if it  failed  it'd  ask
126              for  a passphrase to unlock a keyslot (LUKS) or to derive a vol‐
127              ume key again (plain mode).   The  kernel  keyring  is  used  by
128              default for LUKS2 devices.
130              With  LUKS2  device  additional  <options>  can  be [--token-id,
131              --token-only,  --key-slot,  --key-file,  --keyfile-size,  --key‐
132              file-offset, --timeout, --disable-locks, --disable-keyring].
135       refresh <name>
137              Refreshes parameters of active mapping <name>.
139              Updates parameters of active device <name> without need to deac‐
140              tivate the device (and umount filesystem). Currently it supports
141              parameters refresh on following devices: LUKS1, LUKS2 (including
142              authenticated encryption), plain crypt and loopaes.
144              Mandatory parametrs are identical to those of an open action for
145              respective device type.
147              You   may   change   following   parameters   on   all   devices
148              --perf-same_cpu_crypt,     --perf-submit_from_crypt_cpus     and
149              --allow-discards.
151              Refreshing  device  without  any optional parameter will refresh
152              the device with default setting (respective to device type).
154              LUKS2 only:
156              --integrity-no-journal parameter affects only LUKS2 devices with
157              underlying dm-integrity device.
159              Adding  option  --persistent  stores  any  combination of device
160              parameters  above  in  LUKS2  metadata  (only  after  successful
161              refresh operation).
163              --disable-keyring  parameter  refreshes a device with volume key
164              passed in dm-crypt driver.
167       reencrypt <device> or --active-name <name> [<new_name>]
169              Run resilient reencryption (LUKS2 device only).
171              There are 3 basic modes of operation:
173              · device reencryption (reencrypt)
175              · device encryption (reencrypt --encrypt)
177              · device decryption (reencrypt --decrypt)
179              <device> or --active-name <name> is mandatory parameter.
181              With <device> parameter cryptsetup looks up active  <device>  dm
182              mapping.   If  no  active mapping is detected, it starts offline
183              reencryption otherwise online reencryption takes place.
185              Reencryption process may be safely interrupted  by  a  user  via
186              SIGTERM signal (ctrl+c).
188              To  resume already initialized or interrupted reencryption, just
189              run the cryptsetup reencrypt command again to continue the reen‐
190              cryption  operation.  Reencryption may be resumed with different
191              --resilience  or  --hotzone-size   unless   implicit   datashift
192              resilience  mode  is  used  (reencrypt  --encrypt with --reduce-
193              device-size option).
195              If the reencryption process was interrupted abruptly  (reencryp‐
196              tion  process  crash,  system  crash,  poweroff)  it may require
197              recovery. The recovery is currently run  automatically  on  next
198              activation (action open) when needed.
200              Optional  parameter  <new_name> takes effect only with --encrypt
201              option and it  activates  device  <new_name>  immediately  after
202              encryption  initialization  gets  finished.  That's  useful when
203              device needs to be ready as soon as possible and mounted  (used)
204              before full data area encryption is completed.
206              Action   supports  following  additional  <options>  [--encrypt,
207              --decrypt,   --device-size,   --resilience,   --resilience-hash,
208              --hotzone-size,            --init-only,           --resume-only,
209              --reduce-device-size].


213       Plain dm-crypt encrypts the device sector-by-sector with a single, non-
214       salted  hash of the passphrase. No checks are performed, no metadata is
215       used. There is no formatting operation.  When the raw device is  mapped
216       (opened), the usual device operations can be used on the mapped device,
217       including  filesystem  creation.   Mapped  devices  usually  reside  in
218       /dev/mapper/<name>.
220       The following are valid plain device type actions:
222       open --type plain <device> <name>
223       create <name> <device> (OBSOLETE syntax)
225              Opens (creates a mapping with) <name> backed by device <device>.
227              <options>  can be [--hash, --cipher, --verify-passphrase, --sec‐
228              tor-size, --key-file,  --keyfile-offset,  --key-size,  --offset,
229              --skip,    --size,   --readonly,   --shared,   --allow-discards,
230              --refresh]
232              Example: 'cryptsetup open --type plain /dev/sda10 e1'  maps  the
233              raw encrypted device /dev/sda10 to the mapped (decrypted) device
234              /dev/mapper/e1, which can then be mounted,  fsck-ed  or  have  a
235              filesystem created on it.


238       LUKS,  the  Linux Unified Key Setup, is a standard for disk encryption.
239       It adds a standardized header at the start of the  device,  a  key-slot
240       area directly behind the header and the bulk data area behind that. The
241       whole set is called a 'LUKS container'.  The device that  a  LUKS  con‐
242       tainer  resides  on is called a 'LUKS device'.  For most purposes, both
243       terms can be used interchangeably. But note that when the  LUKS  header
244       is  at  a  nonzero  offset  in  a device, then the device is not a LUKS
245       device anymore, but has a LUKS container stored in it at an offset.
247       LUKS can manage multiple passphrases that can be  individually  revoked
248       or  changed and that can be securely scrubbed from persistent media due
249       to the use of anti-forensic stripes. Passphrases are protected  against
250       brute-force  and  dictionary  attacks  by PBKDF2, which implements hash
251       iteration and salting in one function.
253       LUKS2 is a new version of header format that allows  additional  exten‐
254       sions  like different PBKDF algorithm or authenticated encryption.  You
255       can format device with LUKS2 header if  you  specify  --type  luks2  in
256       luksFormat  command.   For activation, the format is already recognized
257       automatically.
259       Each passphrase, also called a key in this document, is associated with
260       one  of  8 key-slots.  Key operations that do not specify a slot affect
261       the first slot that matches the supplied passphrase or the first  empty
262       slot if a new passphrase is added.
264       The <device> parameter can also be specified by a LUKS UUID in the for‐
265       mat UUID=<uuid>. Translation to  real  device  name  uses  symlinks  in
266       /dev/disk/by-uuid directory.
268       To specify a detached header, the --header parameter can be used in all
269       LUKS commands and always takes precedence over the positional  <device>
270       parameter.
272       The following are valid LUKS actions:
274       luksFormat <device> [<key file>]
276              Initializes  a  LUKS  partition  and sets the initial passphrase
277              (for key-slot 0), either via prompting or via <key  file>.  Note
278              that  if  the second argument is present, then the passphrase is
279              taken from the file given there, without the  need  to  use  the
280              --key-file  option. Also note that for both forms of reading the
281              passphrase from a file you can give  '-'  as  file  name,  which
282              results  in the passphrase being read from stdin and the safety-
283              question being skipped.
285              You can only call luksFormat  on  a  LUKS  device  that  is  not
286              mapped.
288              To use LUKS2, specify --type luks2.
290              <options>   can   be   [--hash,  --cipher,  --verify-passphrase,
291              --key-size,  --key-slot,  --key-file  (takes   precedence   over
292              optional  second  argument),  --keyfile-offset,  --keyfile-size,
293              --use-random   |   --use-urandom,   --uuid,   --master-key-file,
294              --iter-time,  --header,  --pbkdf-force-iterations, --force-pass‐
295              word, --disable-locks].
297              For   LUKS2,   additional   <options>   can   be   [--integrity,
298              --integrity-no-wipe,    --sector-size,   --label,   --subsystem,
299              --pbkdf,  --pbkdf-memory,   --pbkdf-parallel,   --disable-locks,
300              --disable-keyring, --luks2-metadata-size, --luks2-keyslots-size,
301              --keyslot-cipher, --keyslot-key-size].
303              WARNING: Doing a luksFormat on an existing LUKS  container  will
304              make all data the old container permanently irretrievable unless
305              you have a header backup.
307       open --type luks <device> <name>
308       luksOpen <device> <name> (old syntax)
310              Opens the LUKS device <device> and  sets  up  a  mapping  <name>
311              after successful verification of the supplied passphrase.
313              First,  the  passphrase  is searched in LUKS tokens. If it's not
314              found in any token and also the passphrase is not  supplied  via
315              --key-file, the command prompts for it interactively.
317              <options>  can be [--key-file, --keyfile-offset, --keyfile-size,
318              --readonly,   --test-passphrase,   --allow-discards,   --header,
319              --key-slot,  --master-key-file, --token-id, --token-only, --dis‐
320              able-keyring,  --disable-locks,  --type,  --refresh,   --serial‐
321              ize-memory-hard-pbkdf].
323       luksSuspend <name>
325              Suspends  an  active  device  (all  IO operations will block and
326              accesses to the device will wait  indefinitely)  and  wipes  the
327              encryption key from kernel memory. Needs kernel 2.6.19 or later.
329              After this operation you have to use luksResume to reinstate the
330              encryption key and unblock the device or  close  to  remove  the
331              mapped device.
333              WARNING: never suspend the device on which the cryptsetup binary
334              resides.
336              <options> can be [--header, --disable-locks].
338       luksResume <name>
340              Resumes a suspended device and reinstates  the  encryption  key.
341              Prompts  interactively  for  a  passphrase  if --key-file is not
342              given.
344              <options> can be [--key-file, --keyfile-size,  --header,  --dis‐
345              able-keyring, --disable-locks, --type]
347       luksAddKey <device> [<key file with new key>]
349              Adds  a  new passphrase. An existing passphrase must be supplied
350              interactively or via --key-file.  The new passphrase to be added
351              can  be  specified  interactively or read from the file given as
352              positional argument.
354              NOTE: with --unbound option the action creates new unbound LUKS2
355              keyslot.  The  keyslot cannot be used for device activation.  If
356              you don't pass new key via --master-key-file option, new  random
357              key  is generated. Existing passphrase for any active keyslot is
358              not required.
360              <options> can be [--key-file, --keyfile-offset,  --keyfile-size,
361              --new-keyfile-offset,   --new-keyfile-size,  --key-slot,  --mas‐
362              ter-key-file,   --force-password,   --header,   --disable-locks,
363              --iter-time,   --pbkdf,   --pbkdf-force-iterations,   --unbound,
364              --type, --keyslot-cipher, --keyslot-key-size].
366       luksRemoveKey <device> [<key file with passphrase to be removed>]
368              Removes the  supplied  passphrase  from  the  LUKS  device.  The
369              passphrase  to be removed can be specified interactively, as the
370              positional argument or via --key-file.
372              <options> can be [--key-file, --keyfile-offset,  --keyfile-size,
373              --header, --disable-locks, --type]
375              WARNING:  If you read the passphrase from stdin (without further
376              argument or with '-' as an argument to  --key-file),  batch-mode
377              (-q) will be implicitly switched on and no warning will be given
378              when you remove the last remaining passphrase from a  LUKS  con‐
379              tainer.  Removing  the  last passphrase makes the LUKS container
380              permanently inaccessible.
382       luksChangeKey <device> [<new key file>]
384              Changes an existing passphrase. The  passphrase  to  be  changed
385              must  be  supplied  interactively  or  via  --key-file.  The new
386              passphrase can be supplied interactively or in a file  given  as
387              positional argument.
389              If  a key-slot is specified (via --key-slot), the passphrase for
390              that key-slot must be given and the new  passphrase  will  over‐
391              write  the  specified  key-slot. If no key-slot is specified and
392              there is still a free key-slot, then the new passphrase will  be
393              put  into a free key-slot before the key-slot containing the old
394              passphrase is purged. If there is no  free  key-slot,  then  the
395              key-slot with the old passphrase is overwritten directly.
397              WARNING:  If  a  key-slot is overwritten, a media failure during
398              this operation can cause the overwrite to  fail  after  the  old
399              passphrase has been wiped and make the LUKS container inaccessi‐
400              ble.
402              <options> can be [--key-file, --keyfile-offset,  --keyfile-size,
403              --new-keyfile-offset, --iter-time, --pbkdf, --pbkdf-force-itera‐
404              tions,   --new-keyfile-size,    --key-slot,    --force-password,
405              --header,     --disable-locks,     --type,     --keyslot-cipher,
406              --keyslot-key-size].
408       luksConvertKey <device>
410              Converts an existing LUKS2 keyslot to new pbkdf parameters.  The
411              passphrase for keyslot to be converted must be supplied interac‐
412              tively or via --key-file. If no --pbkdf parameters are specified
413              LUKS2 default pbkdf values will apply.
415              If  a  keyslot is specified (via --key-slot), the passphrase for
416              that keyslot must be given. If no keyslot is specified and there
417              is  still  a  free  keyslot, then the new parameters will be put
418              into a free keyslot before the keyslot containing the old param‐
419              eters  is  purged. If there is no free keyslot, then the keyslot
420              with the old parameters is overwritten directly.
422              WARNING: If a keyslot is overwritten,  a  media  failure  during
423              this  operation  can  cause  the overwrite to fail after the old
424              parameters have been wiped and make the LUKS container  inacces‐
425              sible.
427              <options>  can be [--key-file, --keyfile-offset, --keyfile-size,
428              --key-slot,  --header,  --disable-locks,  --iter-time,  --pbkdf,
429              --pbkdf-force-iterations,    --pbkdf-memory,   --pbkdf-parallel,
430              --keyslot-cipher, --keyslot-key-size].
432       luksKillSlot <device> <key slot number>
434              Wipe the key-slot number <key slot> from the LUKS device. Except
435              running  in  batch-mode (-q) a remaining passphrase must be sup‐
436              plied, either interactively or via --key-file.  This command can
437              remove  the last remaining key-slot, but requires an interactive
438              confirmation when doing so. Removing the last passphrase makes a
439              LUKS container permanently inaccessible.
441              <options>  can be [--key-file, --keyfile-offset, --keyfile-size,
442              --header, --disable-locks, --type].
444              WARNING: If you read the passphrase from stdin (without  further
445              argument  or  with '-' as an argument to --key-file), batch-mode
446              (-q) will be implicitly switched on and no warning will be given
447              when  you  remove the last remaining passphrase from a LUKS con‐
448              tainer. Removing the last passphrase makes  the  LUKS  container
449              permanently inaccessible.
451              NOTE:  If  there  is no passphrase provided (on stdin or through
452              --key-file argument) and batch-mode (-q) is active, the key-slot
453              is removed without any other warning.
456       erase <device>
457       luksErase <device>
459              Erase all keyslots and make the LUKS container permanently inac‐
460              cessible.  You do not need to  provide  any  password  for  this
461              operation.
463              WARNING: This operation is irreversible.
465       luksUUID <device>
467              Print the UUID of a LUKS device.
468              Set new UUID if --uuid option is specified.
470       isLuks <device>
472              Returns  true,  if  <device>  is a LUKS device, false otherwise.
473              Use option -v to get human-readable feedback. 'Command  success‐
474              ful.'  means the device is a LUKS device.
476              By specifying --type you may query for specific LUKS version.
478       luksDump <device>
480              Dump the header information of a LUKS device.
482              If  the --dump-master-key option is used, the LUKS device master
483              key is dumped instead of the keyslot info. Together with  --mas‐
484              ter-key-file  option,  master key is dumped to a file instead of
485              standard output. Beware that the master key  cannot  be  changed
486              without  reencryption and can be used to decrypt the data stored
487              in the LUKS container without a passphrase and even without  the
488              LUKS  header.  This means that if the master key is compromised,
489              the whole device has to be erased to prevent further access. Use
490              this option carefully.
492              To  dump the master key, a passphrase has to be supplied, either
493              interactively or via --key-file.
495              <options> can be [--dump-master-key, --key-file,  --keyfile-off‐
496              set,    --keyfile-size,    --header,   --disable-locks,   --mas‐
497              ter-key-file, --type].
499              WARNING: If --dump-master-key is used with  --key-file  and  the
500              argument  to  --key-file  is '-', no validation question will be
501              asked and no warning given.
503       luksHeaderBackup <device> --header-backup-file <file>
505              Stores a binary backup of the LUKS header and keyslot area.
506              Note: Using '-' as filename writes the header backup to  a  file
507              named '-'.
509              WARNING:  This backup file and a passphrase valid at the time of
510              backup allows decryption of the LUKS  data  area,  even  if  the
511              passphrase  was  later  changed or removed from the LUKS device.
512              Also note that with a header backup  you  lose  the  ability  to
513              securely wipe the LUKS device by just overwriting the header and
514              key-slots. You either need to securely erase all header  backups
515              in  addition  or overwrite the encrypted data area as well.  The
516              second option is less secure, as some sectors can survive,  e.g.
517              due to defect management.
519       luksHeaderRestore <device> --header-backup-file <file>
521              Restores  a  binary  backup  of the LUKS header and keyslot area
522              from the specified file.
523              Note: Using '-' as filename reads the header backup from a  file
524              named '-'.
526              WARNING:   Header  and  keyslots  will  be  replaced,  only  the
527              passphrases from the backup will work afterward.
529              This command requires that the master key size and  data  offset
530              of  the  LUKS  header  already  on  the device and of the header
531              backup match. Alternatively, if there is no LUKS header  on  the
532              device, the backup will also be written to it.
534       token <add|remove|import|export> <device>
536              Action  add  creates new keyring token to enable auto-activation
537              of the device.  For the auto-activation, the passphrase must  be
538              stored  in  keyring with the specified description. Usually, the
539              passphrase should be stored in  user  or  user-session  keyring.
540              The token command is supported only for LUKS2.
542              For adding new keyring token, option --key-description is manda‐
543              tory.  Also, new token is assigned to key  slot  specified  with
544              --key-slot  option  or  to  all  active  key  slots  in the case
545              --key-slot option is omitted.
547              To remove existing token, specify the token ID which  should  be
548              removed with --token-id option.
550              WARNING:  The  action  token  remove removes any token type, not
551              just keyring  type  from  token  slot  specified  by  --token-id
552              option.
554              Action  import  can  store  arbitrary  valid token json in LUKS2
555              header. It may be passed via standard input or via  file  passed
556              in  --json-file  option. If you specify --key-slot then success‐
557              fully imported token is also assigned to the key slot.
559              Action export writes requested token json to a file passed  with
560              --json-file or to standard output.
562              <options>    can    be    [--header,   --token-id,   --key-slot,
563              --key-description,      --disable-locks,      --disable-keyring,
564              --json-file].
566       convert <device> --type <format>
568              Converts  the  device  between LUKS1 and LUKS2 format (if possi‐
569              ble).  The conversion will not be performed if there is an addi‐
570              tional LUKS2 feature or LUKS1 has unsupported header size.
572              Conversion  (both  directions)  must  be  performed  on inactive
573              device. There must not be active  dm-crypt  mapping  established
574              for LUKS header requested for conversion.
576              --type option is mandatory with following accepted values: luks1
577              or luks2.
579              WARNING: The convert action can destroy the LUKS header  in  the
580              case  of  a  crash during conversion or if a media error occurs.
581              Always create a header backup before performing this operation!
583              <options> can be [--header, --type].
585       config <device>
587              Set permanent configuration options (store to LUKS header).  The
588              config command is supported only for LUKS2.
590              The permanent options can be --priority to set priority (normal,
591              prefer, ignore) for keyslot (specified by --key-slot) or --label
592              and --subsystem.
594              <options>  can be [--priority, --label, --subsystem, --key-slot,
595              --header].


599       cryptsetup supports mapping loop-AES encrypted partition using  a  com‐
600       patibility mode.
602       open --type loopaes <device> <name> --key-file <keyfile>
603       loopaesOpen <device> <name> --key-file <keyfile>  (old syntax)
605              Opens the loop-AES <device> and sets up a mapping <name>.
607              If  the  key  file is encrypted with GnuPG, then you have to use
608              --key-file=- and decrypt it before use, e.g. like this:
609              gpg --decrypt <keyfile> |  cryptsetup  loopaesOpen  --key-file=-
610              <device> <name>
612              WARNING:  The  loop-AES extension cannot use the direct input of
613              key file on real terminal because the keys are separated by end-
614              of-line and only part of the multi-key file would be read.
615              If you need it in script, just use the pipe redirection:
616              echo  $keyfile  |  cryptsetup  loopaesOpen --key-file=- <device>
617              <name>
619              Use --keyfile-size to specify the proper key length if needed.
621              Use --offset to specify device offset. Note that the units  need
622              to be specified in number of 512 byte sectors.
624              Use --skip to specify the IV offset. If the original device used
625              an offset and but did not use it in IV sector calculations,  you
626              have to explicitly use --skip 0 in addition to the offset param‐
627              eter.
629              Use --hash to override the default hash function for  passphrase
630              hashing (otherwise it is detected according to key size).
632              <options>  can  be  [--key-file,  --key-size,  --offset, --skip,
633              --hash, --readonly, --allow-discards, --refresh].
635       See also section 7 of the FAQ and  http://loop-aes.sourceforge.net  for
636       more information regarding loop-AES.

TCRYPT (TrueCrypt-compatible and VeraCrypt) EXTENSION

639       cryptsetup  supports  mapping  of  TrueCrypt, tcplay or VeraCrypt (with
640       --veracrypt option) encrypted partition using  a  native  Linux  kernel
641       API.   Header  formatting  and  TCRYPT  header change is not supported,
642       cryptsetup never changes TCRYPT header on-device.
644       TCRYPT extension requires kernel userspace crypto API to  be  available
645       (introduced  in  Linux  kernel  2.6.38).  If you are configuring kernel
646       yourself, enable "User-space interface for symmetric key  cipher  algo‐
647       rithms"  in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .con‐
648       fig option).
650       Because TCRYPT header is encrypted, you have to  always  provide  valid
651       passphrase and keyfiles.
653       Cryptsetup  should  recognize all header variants, except legacy cipher
654       chains using LRW encryption mode with 64 bits encryption block  (namely
655       Blowfish  in  LRW  mode is not recognized, this is limitation of kernel
656       crypto API).
658       To recognize a VeraCrypt device use the --veracrypt option.   VeraCrypt
659       is just extension of TrueCrypt header with increased iteration count so
660       unlocking can take quite a lot  of  time  (in  comparison  with  TCRYPT
661       device).
663       To  open a VeraCrypt device with a custom Personal Iteration Multiplier
664       (PIM)  value,  additionally  to  --veracrypt   use  either  the  --ver‐
665       acrypt-pim=<PIM>  option  to  directly  specify the PIM on the command-
666       line or use --veracrypt-query-pim to be prompted for the PIM.
668       The PIM value affects the  number  of  iterations  applied  during  key
669       derivation.    Please    refer    to   https://www.veracrypt.fr/en/Per
670       sonal%20Iterations%20Multiplier%20%28PIM%29.html  for   more   detailed
671       information.
673       NOTE:  Activation  with  tcryptOpen is supported only for cipher chains
674       using LRW or XTS encryption modes.
676       The tcryptDump command should work for all  recognized  TCRYPT  devices
677       and doesn't require superuser privilege.
679       To map system device (device with boot loader where the whole encrypted
680       system resides) use --tcrypt-system  option.   You  can  use  partition
681       device  as  the parameter (parameter must be real partition device, not
682       an image in a file), then only this partition is mapped.
684       If you have the whole TCRYPT device as a file image and you want to map
685       multiple  partition  encrypted  with  system  encryption, please create
686       loopback mapping with partitions first (losetup -P, see losetup(8)  man
687       page for more info), and use loop partition as the device parameter.
689       If  you  use  the  whole base device as a parameter, one device for the
690       whole system encryption is mapped. This  mode  is  available  only  for
691       backward  compatibility  with  older  cryptsetup  versions which mapped
692       TCRYPT system encryption using the whole device.
694       To use hidden  header  (and  map  hidden  device,  if  available),  use
695       --tcrypt-hidden option.
697       To  explicitly  use  backup  (secondary)  header,  use  --tcrypt-backup
698       option.
700       NOTE: There is no protection for a hidden volume if the outer volume is
701       mounted.  The  reason  is  that  if there were any protection, it would
702       require some metadata describing what to protect in  the  outer  volume
703       and the hidden volume would become detectable.
706       open --type tcrypt <device> <name>
707       tcryptOpen <device> <name>  (old syntax)
709              Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a
710              mapping <name>.
712              <options> can be [--key-file, --tcrypt-hidden,  --tcrypt-system,
713              --tcrypt-backup,   --readonly,  --test-passphrase,  --allow-dis‐
714              cards, --veracrypt, --veracrypt-pim, --veracrypt-query-pim].
716              The keyfile parameter allows a combination of file content  with
717              the  passphrase and can be repeated. Note that using keyfiles is
718              compatible with TCRYPT and is different from LUKS keyfile logic.
720              WARNING: Option --allow-discards cannot be combined with  option
721              --tcrypt-hidden.  For  normal mapping, it can cause the destruc‐
722              tion of hidden volume (hidden volume appears as unused space for
723              outer volume so this space can be discarded).
726       tcryptDump <device>
728              Dump the header information of a TCRYPT device.
730              If  the --dump-master-key option is used, the TCRYPT device mas‐
731              ter key is dumped instead of TCRYPT header info. Beware that the
732              master key (or concatenated master keys if cipher chain is used)
733              can be used to decrypt the data stored in the  TCRYPT  container
734              without a passphrase.  This means that if the master key is com‐
735              promised, the whole device has to be erased to  prevent  further
736              access. Use this option carefully.
738              <options>  can  be [--dump-master-key, --key-file, --tcrypt-hid‐
739              den, --tcrypt-system, --tcrypt-backup].
741              The keyfile parameter allows a combination of file content  with
742              the passphrase and can be repeated.
744       See  also  https://en.wikipedia.org/wiki/TrueCrypt for more information
745       regarding TrueCrypt.
747       Please note that cryptsetup does not use TrueCrypt code, please  report
748       all  problems related to this compatibility extension to the cryptsetup
749       project.


752       repair <device>
754              Tries to repair the device metadata if possible. Currently  sup‐
755              ported only for LUKS device type.
757              This  command  is  useful to fix some known benign LUKS metadata
758              header corruptions. Only basic corruptions of unused keyslot are
759              fixable.  This command will only change the LUKS header, not any
760              key-slot data. You may enforce LUKS  version  by  adding  --type
761              option.
763              WARNING:  Always  create  a binary backup of the original header
764              before calling this command.
766       benchmark <options>
768              Benchmarks ciphers and KDF (key derivation  function).   Without
769              parameters, it tries to measure few common configurations.
771              To  benchmark  other  ciphers  or  modes,  you  need  to specify
772              --cipher and --key-size options or --hash for KDF test.
774              NOTE: This benchmark is using memory only and is  only  informa‐
775              tive.  You cannot directly predict real storage encryption speed
776              from it.
778              For  testing  block  ciphers,  this  benchmark  requires  kernel
779              userspace crypto API to be available (introduced in Linux kernel
780              2.6.38).  If you are configuring kernel yourself, enable  "User-
781              space interface for symmetric key cipher algorithms" in "Crypto‐
782              graphic API" section (CRYPTO_USER_API_SKCIPHER .config option).
784              <options> can be [--cipher, --key-size, --hash].


787       --verbose, -v
788              Print more information on command execution.
790       --debug or --debug-json
791              Run in debug mode with full diagnostic logs. Debug output  lines
792              are always prefixed by '#'.  If --debug-json is used, additional
793              LUKS2 JSON data structures are printed.
795       --type <device-type>
796              Specifies required device type, for more info  read  BASIC  COM‐
797              MANDS section.
799       --hash, -h <hash-spec>
800              Specifies  the  passphrase  hash for open (for plain and loopaes
801              device types).
803              Specifies the hash used in the LUKS key setup scheme and  volume
804              key  digest  for luksFormat. The specified hash is used as hash-
805              parameter for PBKDF2 and for the AF splitter.
807              The specified hash name is  passed  to  the  compiled-in  crypto
808              backend.   Different backends may support different hashes.  For
809              luksFormat, the hash algorithm must provide at least 160 bits of
810              output,  which excludes, e.g., MD5. Do not use a non-crypto hash
811              like "crc32" as this breaks security.
813              Values compatible with old version of cryptsetup are "ripemd160"
814              for open --type plain and "sha1" for luksFormat.
816              Use cryptsetup --help to show the defaults.
818       --cipher, -c <cipher-spec>
819              Set the cipher specification string.
821              cryptsetup  --help  shows the compiled-in defaults.  The current
822              default in the distributed sources is "aes-cbc-essiv:sha256" for
823              plain dm-crypt and "aes-xts-plain64" for LUKS.
825              If  a  hash is part of the cipher specification, then it is used
826              as part of the IV generation. For example, ESSIV  needs  a  hash
827              function, while "plain64" does not and hence none is specified.
829              For  XTS mode you can optionally set a key size of 512 bits with
830              the -s option. Key size for XTS mode is  twice  that  for  other
831              modes for the same security level.
833              XTS  mode  requires  kernel 2.6.24 or later and plain64 requires
834              kernel 2.6.33 or later. More information can  be  found  in  the
835              FAQ.
837       --verify-passphrase, -y
838              When interactively asking for a passphrase, ask for it twice and
839              complain if both inputs do not match. Advised  when  creating  a
840              regular  mapping for the first time, or when running luksFormat.
841              Ignored on input from file or stdin.
843       --key-file, -d name
844              Read the passphrase from file.
846              If the name given is "-", then the passphrase will be read  from
847              stdin.   In  this case, reading will not stop at newline charac‐
848              ters.
850              With LUKS, passphrases supplied via --key-file  are  always  the
851              existing  passphrases requested by a command, except in the case
852              of luksFormat where --key-file is equivalent to  the  positional
853              key file argument.
855              If  you  want  to set a new passphrase via key file, you have to
856              use a positional argument to luksAddKey.
858              See section NOTES ON PASSPHRASE PROCESSING for more information.
860       --keyfile-offset value
861              Skip value bytes at the beginning of the key file.   Works  with
862              all commands that accept key files.
864       --keyfile-size, -l value
865              Read a maximum of value bytes from the key file.  The default is
866              to read the whole file up to the compiled-in maximum that can be
867              queried  with  --help.  Supplying more data than the compiled-in
868              maximum aborts the operation.
870              This option is useful to cut trailing newlines, for example.  If
871              --keyfile-offset  is also given, the size count starts after the
872              offset.  Works with all commands that accept key files.
874       --new-keyfile-offset value
875              Skip value bytes at the start when adding a new passphrase  from
876              key file with luksAddKey.
878       --new-keyfile-size  value
879              Read  a maximum of value bytes when adding a new passphrase from
880              key file with luksAddKey.  The default is to read the whole file
881              up  to  the  compiled-in maximum length that can be queried with
882              --help.  Supplying more than the compiled in maximum aborts  the
883              operation.   When  --new-keyfile-offset  is  also given, reading
884              starts after the offset.
886       --master-key-file
887              Use a master key stored in a file.
889              For luksFormat this allows creating a LUKS header with this spe‐
890              cific  master  key. If the master key was taken from an existing
891              LUKS header and all other parameters are the same, then the  new
892              header  decrypts  the  data encrypted with the header the master
893              key was taken from.
895              Action luksDump together with --dump-master-key option: The vol‐
896              ume  (master)  key  is stored in a file instead of being printed
897              out to standard output.
899              WARNING: If you create your own master key,  you  need  to  make
900              sure  to  do  it  right.  Otherwise,  you can end up with a low-
901              entropy or otherwise partially predictable master key which will
902              compromise security.
904              For  luksAddKey this allows adding a new passphrase without hav‐
905              ing to know an existing one.
907              For open this allows one to open the LUKS device without  giving
908              a passphrase.
910       --dump-master-key
911              For  luksDump  this  option  includes the master key in the dis‐
912              played information. Use with care, as the master key can be used
913              to bypass the passphrases, see also option --master-key-file.
915       --json-file
916              Read  token  json  from  a  file or write token to it. See token
917              action for more information. --json-file=- reads json from stan‐
918              dard input or writes it to standard output respectively.
920       --use-random
922       --use-urandom
923              For  luksFormat  these options define which kernel random number
924              generator will be used to create the  master  key  (which  is  a
925              long-term key).
927              See  NOTES ON RANDOM NUMBER GENERATORS for more information. Use
928              cryptsetup --help to show the compiled-in default random  number
929              generator.
931              WARNING:  In  a  low-entropy situation (e.g. in an embedded sys‐
932              tem), both selections are problematic.  Using  /dev/urandom  can
933              lead  to  weak  keys.   Using /dev/random can block a long time,
934              potentially forever, if not enough entropy can be  harvested  by
935              the kernel.
937       --key-slot, -S <0-7>
938              For  LUKS  operations that add key material, this options allows
939              you to specify which key slot is selected for the new key.  This
940              option can be used for luksFormat, and luksAddKey.
941              In  addition,  for open, this option selects a specific key-slot
942              to compare the passphrase  against.   If  the  given  passphrase
943              would only match a different key-slot, the operation fails.
945       --key-size, -s <bits>
946              Sets  key  size in bits. The argument has to be a multiple of 8.
947              The possible key-sizes are limited by the cipher and mode used.
949              See /proc/crypto for more information.  Note  that  key-size  in
950              /proc/crypto is stated in bytes.
952              This  option  can  be  used for open --type plain or luksFormat.
953              All other LUKS actions will use the key-size  specified  in  the
954              LUKS  header.   Use  cryptsetup  --help  to show the compiled-in
955              defaults.
957       --size, -b <number of 512 byte sectors>
958              Set the size of the device in sectors of 512 bytes.  This option
959              is only relevant for the open and resize actions.
961       --offset, -o <number of 512 byte sectors>
962              Start  offset  in  the backend device in 512-byte sectors.  This
963              option is only relevant  for  the  open  action  with  plain  or
964              loopaes device types or for LUKS devices in luksFormat.
966              For  LUKS, the --offset option sets the data offset (payload) of
967              data device and must be be aligned to 4096-byte sectors (must be
968              multiple   of   8).    This   option  cannot  be  combined  with
969              --align-payload option.
971       --skip, -p <number of 512 byte sectors>
972              Start offset used in IV calculation  in  512-byte  sectors  (how
973              many  sectors  of  the encrypted data to skip at the beginning).
974              This option is only relevant for the open action with  plain  or
975              loopaes device types.
977              Hence,  if  --offset n, and --skip s, sector n (the first sector
978              of the encrypted device) will get a sector number of s  for  the
979              IV calculation.
981       --device-size size[units]
982              Instead of real device size, use specified value.
984              With  reencrypt  action  it means that only specified area (from
985              the start of the device to the specified  size)  will  be  reen‐
986              crypted.
988              With resize action it sets new size of the device.
990              If no unit suffix is specified, the size is in bytes.
992              Unit  suffix  can  be  S  for  512  byte  sectors,  K/M/G/T  (or
993              KiB,MiB,GiB,TiB) for units with 1024  base  or  KB/MB/GB/TB  for
994              1000 base (SI scale).
996              WARNING:  This is destructive operation when used with reencrypt
997              command.
999       --readonly, -r
1000              set up a read-only mapping.
1002       --shared
1003              Creates an additional mapping for one common ciphertext  device.
1004              Arbitrary  mappings are supported.  This option is only relevant
1005              for the open --type  plain  action.  Use  --offset,  --size  and
1006              --skip to specify the mapped area.
1008       --pbkdf <PBKDF spec>
1009              Set Password-Based Key Derivation Function (PBKDF) algorithm for
1010              LUKS keyslot.  The PBKDF can be: pbkdf2 (for PBKDF2 according to
1011              RFC2898),  argon2i  for  Argon2i  or  argon2id for Argon2id (see
1012              https://www.cryptolux.org/index.php/Argon2 for more info).
1014              For LUKS1, only PBKDF2 is accepted (no need to use this option).
1015              The  default PBKDF2 for LUKS2 is set during compilation time and
1016              is available in cryptsetup --help output.
1018              A PBKDF is used for increasing dictionary and brute-force attack
1019              cost  for  keyslot passwords. The parameters can be time, memory
1020              and parallel cost.
1022              For PBKDF2, only time cost (number of iterations) applies.   For
1023              Argon2i/id,  there  is  also memory cost (memory required during
1024              the process of key derivation)  and  parallel  cost  (number  of
1025              threads that run in parallel during the key derivation.
1027              Note  that  increasing  memory  cost also increases time, so the
1028              final parameter values are measured by a benchmark.  The  bench‐
1029              mark  tries  to  find iteration time (--iter-time) with required
1030              memory cost --pbkdf-memory. If it is not  possible,  the  memory
1031              cost  is  decreased as well.  The parallel cost --pbkdf-parallel
1032              is constant, is is checked against available CPU cores  (if  not
1033              available, it is decreased) and the maximum parallel cost is 4.
1035              You  can  see  all PBKDF parameters for particular LUKS2 keyslot
1036              with luksDump command.
1038              NOTE: If you do not want to use benchmark and  want  to  specify
1039              all   parameters  directly,  use  --pbkdf-force-iterations  with
1040              --pbkdf-memory and --pbkdf-parallel.   This  will  override  the
1041              values  without  benchmarking.  Note it can cause extremely long
1042              unlocking time. Use only is specified cases, for example, if you
1043              know that the formatted device will be used on some small embed‐
1044              ded system.  In this case, the LUKS PBKDF2 digest will be set to
1045              the minimum iteration count.
1047       --iter-time, -i <number of milliseconds>
1048              The  number  of milliseconds to spend with PBKDF passphrase pro‐
1049              cessing.  This option is only relevant for LUKS operations  that
1050              set  or  change  passphrases,  such as luksFormat or luksAddKey.
1051              Specifying 0 as parameter selects the compiled-in default.
1053       --pbkdf-memory <number>
1054              Set the memory cost for PBKDF (for Argon2i/id the number  repre‐
1055              sents  kilobytes).   Note that it is maximal value, PBKDF bench‐
1056              mark or available physical memory can decrease it.  This  option
1057              is not available for PBKDF2.
1059       --pbkdf-parallel <number>
1060              Set  the  parallel  cost for PBKDF (number of threads, up to 4).
1061              Note that it is maximal value, it is decreased automatically  if
1062              CPU  online  count  is  lower.  This option is not available for
1063              PBKDF2.
1065       --pbkdf-force-iterations <num>
1066              Avoid PBKDF benchmark and set time cost  (iterations)  directly.
1067              It  can  be used for LUKS/LUKS2 device only.  See --pbkdf option
1068              for more info.
1070       --batch-mode, -q
1071              Suppresses all confirmation questions. Use with care!
1073              If the -y option is not specified, this option also switches off
1074              the passphrase verification for luksFormat.
1076       --progress-frequency <seconds>
1077              Print separate line every <seconds> with wipe progress.
1079       --timeout, -t <number of seconds>
1080              The number of seconds to wait before timeout on passphrase input
1081              via terminal. It is relevant every time a passphrase  is  asked,
1082              for  example  for  open,  luksFormat  or  luksAddKey.  It has no
1083              effect if used in conjunction with --key-file.
1084              This option is useful when the system should not  stall  if  the
1085              user  does not input a passphrase, e.g. during boot. The default
1086              is a value of 0 seconds, which means to wait forever.
1088       --tries, -T
1089              How often the input of the passphrase shall  be  retried.   This
1090              option is relevant every time a passphrase is asked, for example
1091              for open, luksFormat or luksAddKey.  The default is 3 tries.
1093       --align-payload <number of 512 byte sectors>
1094              Align payload at a boundary of  value  512-byte  sectors.   This
1095              option is relevant for luksFormat.
1097              If not specified, cryptsetup tries to use the topology info pro‐
1098              vided by the kernel for the underlying device to get the optimal
1099              alignment.   If not available (or the calculated value is a mul‐
1100              tiple of the default) data is  by  default  aligned  to  a  1MiB
1101              boundary (i.e. 2048 512-byte sectors).
1103              For  a detached LUKS header, this option specifies the offset on
1104              the data device. See also the --header option.
1106              WARNING: This option is  DEPRECATED  and  has  often  unexpected
1107              impact  to the data offset and keyslot area size (for LUKS2) due
1108              to the complex rounding.   For  fixed  data  device  offset  use
1109              --offset option instead.
1112       --uuid=UUID
1113              Use the provided UUID for the luksFormat command instead of gen‐
1114              erating a new one. Changes the existing UUID when used with  the
1115              luksUUID command.
1117              The  UUID  must  be  provided  in the standard UUID format, e.g.
1118              12345678-1234-1234-1234-123456789abc.
1120       --allow-discards
1121              Allow the use of discard (TRIM) requests for the  device.   This
1122              option is only relevant for open action.
1124              WARNING:  This  command  can  have  a  negative  security impact
1125              because it can make filesystem-level operations visible  on  the
1126              physical  device.  For  example,  information leaking filesystem
1127              type, used space, etc. may  be  extractable  from  the  physical
1128              device  if  the  discarded  blocks  can  be located later. If in
1129              doubt, do not use it.
1131              A kernel version of 3.1 or later is needed. For earlier kernels,
1132              this option is ignored.
1134       --perf-same_cpu_crypt
1135              Perform  encryption using the same cpu that IO was submitted on.
1136              The default is to use an unbound workqueue  so  that  encryption
1137              work  is  automatically  balanced  between available CPUs.  This
1138              option is only relevant for open action.
1140              NOTE: This option is available only for low-level dm-crypt  per‐
1141              formance  tuning,  use  only if you need a change to default dm-
1142              crypt behaviour. Needs kernel 4.0 or later.
1144       --perf-submit_from_crypt_cpus
1145              Disable offloading writes to a separate thread after encryption.
1146              There  are  some situations where offloading write bios from the
1147              encryption threads to a single thread degrades performance  sig‐
1148              nificantly.   The  default  is to offload write bios to the same
1149              thread.  This option is only relevant for open action.
1151              NOTE: This option is available only for low-level dm-crypt  per‐
1152              formance  tuning,  use  only if you need a change to default dm-
1153              crypt behaviour. Needs kernel 4.0 or later.
1155       --test-passphrase
1156              Do not activate the device, just verify passphrase.  This option
1157              is only relevant for open action (the device mapping name is not
1158              mandatory if this option is used).
1160       --header <device or file storing the LUKS header>
1161              Use a detached (separated) metadata device  or  file  where  the
1162              LUKS  header  is stored. This option allows one to store cipher‐
1163              text and LUKS header on different devices.
1165              This option is only relevant for LUKS devices and  can  be  used
1166              with  the  luksFormat, open, luksSuspend, luksResume, status and
1167              resize commands.
1169              For luksFormat with a file name as the argument to --header, the
1170              file  will  be  automatically created if it does not exist.  See
1171              the cryptsetup FAQ for header size calculation.
1173              For other commands that change the LUKS  header  (e.g.  luksAdd‐
1174              Key),  specify  the device or file with the LUKS header directly
1175              as the LUKS device.
1177              If used with luksFormat, the --align-payload option is taken  as
1178              absolute sector alignment on ciphertext device and can be zero.
1180              WARNING:  There is no check whether the ciphertext device speci‐
1181              fied actually belongs to the header  given.  In  fact,  you  can
1182              specify  an  arbitrary  device as the ciphertext device for open
1183              with the --header option. Use with care.
1185       --header-backup-file <file>
1186              Specify file with header backup  for  luksHeaderBackup  or  luk‐
1187              sHeaderRestore actions.
1189       --force-password
1190              Do not use password quality checking for new LUKS passwords.
1192              This   option   applies   only  to  luksFormat,  luksAddKey  and
1193              luksChangeKey and is ignored  if  cryptsetup  is  built  without
1194              password quality checking support.
1196              For  more info about password quality check, see the manual page
1197              for pwquality.conf(5) and passwdqc.conf(5).
1199       --deferred
1200              Defers device removal in  close  command  until  the  last  user
1201              closes it.
1203       --disable-locks
1204              Disable  lock  protection  for metadata on disk.  This option is
1205              valid only for LUKS2 and ignored for other formats.
1207              WARNING: Do not use this option unless you run cryptsetup  in  a
1208              restricted  environment  where  locking is impossible to perform
1209              (where /run directory cannot be used).
1211       --disable-keyring
1212              Do not load volume key in kernel keyring and store  it  directly
1213              in  the  dm-crypt target instead.  This option is supported only
1214              for the LUKS2 format.
1216       --key-description <text>
1217              Set key description in keyring for use with token command.
1219       --priority <normal|prefer|ignore>
1220              Set a priority for LUKS2 keyslot.  The  prefer  priority  marked
1221              slots  are  tried  before normal priority.  The ignored priority
1222              means, that slot is never used, if not explicitly  requested  by
1223              --key-slot option.
1225       --token-id
1226              Specify  what token to use in actions token, open or resize.  If
1227              omitted, all available tokens will be checked before  proceeding
1228              further with passphrase prompt.
1230       --token-only
1231              Do  not  proceed  further  with  action  (any  of token, open or
1232              resize) if token activation failed. Without the  option,  action
1233              asks for passphrase to proceed further.
1235       --sector-size <bytes>
1236              Set  sector  size for use with disk encryption. It must be power
1237              of two and in range 512 - 4096 bytes. The default is  512  bytes
1238              sectors.  This option is available only in the LUKS2 mode.
1240              Note  that if sector size is higher than underlying device hard‐
1241              ware sector and there is not integrity protection that uses data
1242              journal,  using this option can increase risk on incomplete sec‐
1243              tor writes during a power fail.
1245              If used together with --integrity option and dm-integrity  jour‐
1246              nal,  the atomicity of writes is guaranteed in all cases (but it
1247              cost write performance - data has to be written twice).
1249              Increasing sector size from 512 bytes to 4096 bytes can  provide
1250              better  performance  on  most  of the modern storage devices and
1251              also with some hw encryption accelerators.
1253       --persistent
1254              If used with LUKS2 devices and activation  commands  like  open,
1255              the  specified  activation  flags  are persistently written into
1256              metadata and used next time automatically even for normal  acti‐
1257              vation.   (No  need to use cryptab or other system configuration
1258              files.)     Only    --allow-discards,     --perf-same_cpu_crypt,
1259              --perf-submit_from_crypt_cpus  and --integrity-no-journal can be
1260              stored persistently.
1262       --refresh
1263              Refreshes an active device  with  new  set  of  parameters.  See
1264              action refresh description for more details.
1266       --label <LABEL>
1267              --subsystem  <SUBSYSTEM> Set label and subsystem description for
1268              LUKS2 device, can be used in config  and  format  actions.   The
1269              label and subsystem are optional fields and can be later used in
1270              udev scripts for triggering user actions once device  marked  by
1271              these labels is detected.
1273       --integrity <integrity algorithm>
1274              Specify  integrity  algorithm  to be used for authenticated disk
1275              encryption in LUKS2.
1277              WARNING:  This  extension  is  EXPERIMENTAL  and  requires   dm-
1278              integrity  kernel  target (available since kernel version 4.12).
1279              For native AEAD modes, also  enable  "User-space  interface  for
1280              AEAD  cipher  algorithms"  in  "Cryptographic API" section (CON‐
1281              FIG_CRYPTO_USER_API_AEAD .config option).
1283              For more info, see AUTHENTICATED DISK ENCRYPTION section.
1285       --luks2-metadata-size <size>
1286              This option can be used to enlarge  the  LUKS2  metadata  (JSON)
1287              area.   The size includes 4096 bytes for binary metadata (usable
1288              JSON area is smaller of the binary area).   According  to  LUKS2
1289              specification,  only  these  values  are valid: 16, 32, 64, 128,
1290              256, 512, 1024, 2048 and 4096 kB The  <size>  can  be  specified
1291              with unit suffix (for example 128k).
1293       --luks2-keyslots-size <size>
1294              This option can be used to set specific size of the LUKS2 binary
1295              keyslot area (key material is encrypted there). The  value  must
1296              be  aligned  to  multiple of 4096 bytes with maximum size 128MB.
1297              The <size> can be specified with unit suffix (for example 128k).
1299       --keyslot-cipher <cipher-spec>
1300              This option can be used to set specific  cipher  encryption  for
1301              the LUKS2 keyslot area.
1303       --keyslot-key-size <bits>
1304              This  option  can be used to set specific key size for the LUKS2
1305              keyslot area.
1307       --integrity-no-journal
1308              Activate device with integrity  protection  without  using  data
1309              journal  (direct  write  of data and integrity tags).  Note that
1310              without journal power fail can cause non-atomic write  and  data
1311              corruption.  Use only if journalling is performed on a different
1312              storage layer.
1314       --integrity-no-wipe
1315              Skip wiping of device authentication (integrity)  tags.  If  you
1316              skip  this step, sectors will report invalid integrity tag until
1317              an application write to the sector.
1319              NOTE: Even some writes to the device can fail if  the  write  is
1320              not aligned to page size and page-cache initiates read of a sec‐
1321              tor with invalid integrity tag.
1323       --unbound
1325              Creates new LUKS2 unbound keyslot.  See  luksAddKey  action  for
1326              more details.
1328       --tcrypt-hidden
1329              --tcrypt-system  --tcrypt-backup Specify which TrueCrypt on-disk
1330              header will be used to open the device.  See TCRYPT section  for
1331              more info.
1333       --veracrypt
1334              Allow VeraCrypt compatible mode. Only for TCRYPT extension.  See
1335              TCRYPT section for more info.
1337       --veracrypt-pim
1338              --veracrypt-query-pim Use a custom Personal Iteration Multiplier
1339              (PIM) for VeraCrypt device.  See TCRYPT section for more info.
1341       --serialize-memory-hard-pbkdf
1342              Use  a global lock to serialize unlocking of keyslots using mem‐
1343              ory-hard PBKDF.
1345              NOTE: This is (ugly) workaround for a  specific  situation  when
1346              multiple devices are activated in parallel and system instead of
1347              reporting out of memory starts  unconditionally  stop  processes
1348              using out-of-memory killer.
1350              DO  NOT USE this switch until you are implementing boot environ‐
1351              ment with parallel devices activation!
1353       --encrypt
1354              Initialize (and run) device encryption (reencrypt action parame‐
1355              ter)
1357       --decrypt
1358              Initialize (and run) device decryption (reencrypt action parame‐
1359              ter)
1361       --init-only
1362              Initialize reencryption (any variant) operation in  LUKS2  meta‐
1363              data  only  and exit. If any reencrypt operation is already ini‐
1364              tialized in metadata, the  command  with  --init-only  parameter
1365              fails.
1367       --resume-only
1368              Resume reencryption (any variant) operation already described in
1369              LUKS2 metadata. If no reencrypt operation  is  initialized,  the
1370              command  with --resume-only parameter fails. Useful for resuming
1371              reencrypt operation without accidentally  triggering  new  reen‐
1372              cryption operation.
1374       --resilience <mode>
1375              Reencryption  resilience mode can be one of checksum, journal or
1376              none.
1378              checksum: default mode, where individual checksums of ciphertext
1379              hotzone  sectors  are stored, so the recovery process can detect
1380              which sectors where already reencrypted. It  requires  that  the
1381              device sector write is atomic.
1383              journal:  the  hotzone  is  journaled in the binary area (so the
1384              data are written twice).
1386              none: performance mode. There is no protection and the only  way
1387              it's  safe  to interrupt the reencryption is similar to old off‐
1388              line reencryption utility. (ctrl+c).
1390              The option is ignored if reencryption with datashift mode is  in
1391              progress.
1393       --resilience-hash <hash>
1394              The  hash  algorithm used with "--resilience checksum" only. The
1395              default hash is sha256. With other resilience  modes,  the  hash
1396              parameter is ignored.
1398       --hotzone-size <size>
1399              This  option  can  be  used to set an upper limit on the size of
1400              reencryption area (hotzone).  The <size> can be  specified  with
1401              unit suffix (for example 50M). Note that actual hotzone size may
1402              be less than specified <size> due  to  other  limitations  (free
1403              space in keyslots area or available memory).
1405       --reduce-device-size <size>
1406              Initialize  LUKS2  reencryption  with data device size reduction
1407              (currently only --encrypt variant is supported).
1409              Last <size> sectors of <device> will be used  to  properly  ini‐
1410              tialize  device reencryption. That means any data at last <size>
1411              sectors will be lost.
1413              It could be useful if you added some space to underlying  parti‐
1414              tion  or  logical  volume  (so  last  <size> sectors contains no
1415              data).
1417              Recommended minimal size is twice the default LUKS2 header  size
1418              (--reduce-device-size  32M)  for  --encrypt use case. Be sure to
1419              have enough (at least --reduce-device-size value of  free  space
1420              at the end of <device>).
1422              WARNING: This is a destructive operation and cannot be reverted.
1423              Use with extreme care - accidentally overwritten filesystems are
1424              usually unrecoverable.
1426       --version
1427              Show the program version.
1429       --usage
1430              Show short option help.
1432       --help, -?
1433              Show help text and default parameters.


1436       Cryptsetup returns 0 on success and a non-zero value on error.
1438       Error  codes are: 1 wrong parameters, 2 no permission (bad passphrase),
1439       3 out of memory, 4 wrong device specified, 5 device already  exists  or
1440       device is busy.


1443       Note  that  no  iterated  hashing or salting is done in plain mode.  If
1444       hashing is done, it is a single  direct  hash.  This  means  that  low-
1445       entropy passphrases are easy to attack in plain mode.
1447       From  a  terminal: The passphrase is read until the first newline, i.e.
1448       '\n'.  The input without the newline character is  processed  with  the
1449       default  hash  or the hash specified with --hash.  The hash result will
1450       be truncated to the key size of the used cipher, or the size  specified
1451       with -s.
1453       From stdin: Reading will continue until a newline (or until the maximum
1454       input size is reached), with the trailing newline stripped. The maximum
1455       input  size is defined by the same compiled-in default as for the maxi‐
1456       mum key file size and can be overwritten using --keyfile-size option.
1458       The data read will be hashed with the default hash or the  hash  speci‐
1459       fied with --hash.  The hash result will be truncated to the key size of
1460       the used cipher, or the size specified with -s.
1462       Note that if --key-file=- is used  for  reading  the  key  from  stdin,
1463       trailing newlines are not stripped from the input.
1465       If  "plain"  is  used as argument to --hash, the input data will not be
1466       hashed. Instead, it will be zero padded (if shorter than the key  size)
1467       or  truncated  (if  longer  than the key size) and used directly as the
1468       binary key. This is useful for directly specifying a  binary  key.   No
1469       warning  will  be  given  if the amount of data read from stdin is less
1470       than the key size.
1472       From a key file: It will be truncated to  the  key  size  of  the  used
1473       cipher or the size given by -s and directly used as a binary key.
1475       WARNING:  The  --hash  argument is being ignored.  The --hash option is
1476       usable only for stdin input in plain mode.
1478       If the key file is shorter than the key, cryptsetup will quit  with  an
1479       error.   The  maximum  input  size  is  defined by the same compiled-in
1480       default as for the maximum key file size and can be  overwritten  using
1481       --keyfile-size option.


1486       LUKS uses PBKDF2 to protect against dictionary attacks and to give some
1487       protection to low-entropy passphrases (see RFC 2898 and the  cryptsetup
1488       FAQ).
1490       From  a  terminal:  The  passphrase is read until the first newline and
1491       then processed by PBKDF2 without the newline character.
1493       From stdin: LUKS will read passphrases from stdin up to the first  new‐
1494       line  character  or  the compiled-in maximum key file length. If --key‐
1495       file-size is given, it is ignored.
1497       From key file: The complete keyfile is read up to the compiled-in maxi‐
1498       mum  size.  Newline  characters  do not terminate the input. The --key‐
1499       file-size option can be used to limit what is read.
1501       Passphrase processing: Whenever a passphrase is added to a LUKS  header
1502       (luksAddKey,  luksFormat),  the  user may specify how much the time the
1503       passphrase processing should consume. The time is used to determine the
1504       iteration  count  for PBKDF2 and higher times will offer better protec‐
1505       tion for low-entropy passphrases, but open will  take  longer  to  com‐
1506       plete.  For  passphrases  that  have  entropy  higher than the used key
1507       length, higher iteration times will not increase security.
1509       The default setting of one or two seconds is sufficient for most  prac‐
1510       tical  cases.  The only exception is a low-entropy passphrase used on a
1511       device with a slow CPU, as this will result in a low  iteration  count.
1512       On  a  slow  device, it may be advisable to increase the iteration time
1513       using the --iter-time option in order  to  obtain  a  higher  iteration
1514       count. This does slow down all later luksOpen operations accordingly.


1517       LUKS  checks  for  a  valid  passphrase  when an encrypted partition is
1518       unlocked. The behavior of plain dm-crypt is different.  It will  always
1519       decrypt  with  the  passphrase given. If the given passphrase is wrong,
1520       the device mapped by plain  dm-crypt  will  essentially  still  contain
1521       encrypted data and will be unreadable.


1524       The  available  combinations  of  ciphers,  modes, hashes and key sizes
1525       depend on kernel support. See /proc/crypto  for  a  list  of  available
1526       options.  You  might  need  to load additional kernel crypto modules in
1527       order to get more options.
1529       For the --hash option, if the crypto backend  is  libgcrypt,  then  all
1530       algorithms  supported  by  the gcrypt library are available.  For other
1531       crypto backends, some algorithms may be missing.


1534       Mathematics can't be bribed. Make sure you keep your passphrases  safe.
1535       There  are a few nice tricks for constructing a fallback, when suddenly
1536       out of the blue, your brain refuses to cooperate.  These fallbacks need
1537       LUKS,  as  it's  only  possible with LUKS to have multiple passphrases.
1538       Still, if your  attacker  model  does  not  prevent  it,  storing  your
1539       passphrase in a sealed envelope somewhere may be a good idea as well.


1542       Random Number Generators (RNG) used in cryptsetup are always the kernel
1543       RNGs without any modifications or additions to data stream produced.
1545       There are two types  of  randomness  cryptsetup/LUKS  needs.  One  type
1546       (which always uses /dev/urandom) is used for salts, the AF splitter and
1547       for wiping deleted keyslots.
1549       The second type is used for the volume (master)  key.  You  can  switch
1550       between  using /dev/random and /dev/urandom  here, see --use-random and
1551       --use-urandom options. Using /dev/random on  a  system  without  enough
1552       entropy  sources  can  cause  luksFormat  to  block until the requested
1553       amount of random data is gathered. In a low-entropy situation (embedded
1554       system), this can take a very long time and potentially forever. At the
1555       same time, using /dev/urandom in a low-entropy situation  will  produce
1556       low-quality  keys.  This is a serious problem, but solving it is out of
1557       scope for a mere man-page.  See urandom(4) for more information.


1560       Since Linux kernel version 4.12 dm-crypt  supports  authenticated  disk
1561       encryption.
1563       Normal disk encryption modes are length-preserving (plaintext sector is
1564       of the same size as a ciphertext sector) and can provide only confiden‐
1565       tiality protection, but not cryptographically sound data integrity pro‐
1566       tection.
1568       Authenticated modes require additional space per-sector for authentica‐
1569       tion  tag  and use Authenticated Encryption with Additional Data (AEAD)
1570       algorithms.
1572       If you configure LUKS2 device with  data  integrity  protection,  there
1573       will  be  an  underlying dm-integrity device, which provides additional
1574       per-sector metadata space and also provide data journal  protection  to
1575       ensure  atomicity  of  data and metadata update.  Because there must be
1576       additional space for metadata and journal, the available space for  the
1577       device will be smaller than for length-preserving modes.
1579       The  dm-crypt device then resides on top of such a dm-integrity device.
1580       All activation and deactivation of this device stack  is  performed  by
1581       cryptsetup, there is no difference in using luksOpen for integrity pro‐
1582       tected devices.  If you want to format LUKS2 device with data integrity
1583       protection, use --integrity option.
1585       Some  integrity modes requires two independent keys (key for encryption
1586       and for authentication).  Both  these  keys  are  stored  in  one  LUKS
1587       keyslot.
1589       WARNING:  All support for authenticated modes is experimental and there
1590       are only some modes available for now. Note that there are a  very  few
1591       authenticated  encryption algorithms that are suitable for disk encryp‐
1592       tion.


1596       Cryptsetup is usually used directly on a block device  (disk  partition
1597       or  LVM  volume). However, if the device argument is a file, cryptsetup
1598       tries to allocate a loopback device and map it  into  this  file.  This
1599       mode  requires  Linux  kernel  2.6.25 or more recent which supports the
1600       loop autoclear flag (loop device is cleared on the last close automati‐
1601       cally). Of course, you can always map a file to a loop-device manually.
1602       See the cryptsetup FAQ for an example.
1604       When device mapping is active, you can see the loop backing file in the
1605       status command output. Also see losetup(8).

LUKS2 header locking

1608       The  LUKS2  on-disk metadata is updated in several steps and to achieve
1609       proper atomic update, there is a locking mechanism.  For  an  image  in
1610       file, code uses flock(2) system call.  For a block device, lock is per‐
1611       formed over a special file stored in a locking  directory  (by  default
1612       /run/lock/cryptsetup).   The  locking  directory should be created with
1613       the proper security context by  the  distribution  during  the  boot-up
1614       phase.  Only LUKS2 uses locks, other formats do not use this mechanism.


1617       The reload action is no longer supported.  Please use dmsetup(8) if you
1618       need to directly manipulate with the device mapping table.
1620       The luksDelKey was replaced with luksKillSlot.


1623       Report bugs, including ones in the  documentation,  on  the  cryptsetup
1624       mailing  list at <dm-crypt@saout.de> or in the 'Issues' section on LUKS
1625       website.  Please attach the output  of  the  failed  command  with  the
1626       --debug option added.


1629       cryptsetup originally written by Jana Saout <jana@saout.de>
1630       The LUKS extensions and original man page were written by Clemens Fruh‐
1631       wirth <clemens@endorphin.org>.
1632       Man page extensions by Milan Broz <gmazyland@gmail.com>.
1633       Man page rewrite and extension by Arno Wagner <arno@wagner.name>.
1636       Copyright © 2004 Jana Saout
1637       Copyright © 2004-2006 Clemens Fruhwirth
1638       Copyright © 2012-2014 Arno Wagner
1639       Copyright © 2009-2019 Red Hat, Inc.
1640       Copyright © 2009-2019 Milan Broz
1642       This is free software; see the source for copying conditions.  There is
1643       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
1644       PURPOSE.


1647       The LUKS website at https://gitlab.com/cryptsetup/cryptsetup/
1649       The cryptsetup FAQ, contained in the distribution package and online at
1650       https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
1652       The cryptsetup mailing list and list archive, see FAQ entry 1.6.
1654       The   LUKS  on-disk  format  specification  available  at  https://git
1655       lab.com/cryptsetup/cryptsetup/wikis/Specification
1659cryptsetup                       January 2019                    CRYPTSETUP(8)