1CRYPTSETUP(8)                Maintenance Commands                CRYPTSETUP(8)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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.
17
18       In  addition,  cryptsetup provides limited support for the use of loop-
19       AES volumes and for TrueCrypt compatible volumes.
20
21

PLAIN DM-CRYPT OR LUKS?

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

WARNINGS

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.
33
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.
38
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.
48
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.
57
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.
66
67

BASIC COMMANDS

69       The following are valid actions for all supported device types.
70
71       open <device> <name> --type <device_type>
72
73              Opens (creates a mapping with) <name> backed by device <device>.
74
75              Device  type can be plain, luks (default), luks1, luks2, loopaes
76              or tcrypt.
77
78              For backward compatibility there are open command aliases:
79
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
85
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.
90
91       close <name>
92
93              Removes  the existing mapping <name> and wipes the key from ker‐
94              nel memory.
95
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).
100
101              <options> can be [--deferred]
102
103
104       status <name>
105
106              Reports the status for the mapping <name>.
107
108       resize <name>
109
110              Resizes an active mapping <name>.
111
112              If  --size  (in 512-bytes sectors) is not specified, the size is
113              computed from the underlying device. For LUKS it is the size  of
114              the  underlying device without the area reserved for LUKS header
115              (see data payload offset in luksDump command).  For plain  crypt
116              device, the whole device size is used.
117
118              Note  that this does not change the raw device geometry, it just
119              changes how many sectors of the raw device  are  represented  in
120              the mapped device.
121
122              If  cryptsetup  detected  volume key for active device loaded in
123              kernel  keyring  service,  resize  action  would  first  try  to
124              retrieve  the  key  using a token and only if it failed it'd ask
125              for a passphrase to unlock a keyslot (LUKS) or to derive a  vol‐
126              ume  key  again  (plain  mode).   The  kernel keyring is used by
127              default for LUKS2 devices.
128
129              With LUKS2  device  additional  <options>  can  be  [--token-id,
130              --token-only,  --key-slot,  --key-file,  --keyfile-size,  --key‐
131              file-offset, --timeout, --disable-locks, --disable-keyring].
132
133
134       refresh <name>
135
136              Refreshes parameters of active mapping <name>.
137
138              Updates parameters of active device <name> without need to deac‐
139              tivate the device (and umount filesystem). Currently it supports
140              parameters refresh on following devices: LUKS1, LUKS2 (including
141              authenticated encryption), plain crypt and loopaes.
142
143              Mandatory parametrs are identical to those of an open action for
144              respective device type.
145
146              You   may   change   following   parameters   on   all   devices
147              --perf-same_cpu_crypt,     --perf-submit_from_crypt_cpus     and
148              --allow-discards.
149
150              Refreshing device without any optional  parameter  will  refresh
151              the device with default setting (respective to device type).
152
153              LUKS2 only:
154
155              --integrity-no-journal parameter affects only LUKS2 devices with
156              underlying dm-integrity device.
157
158              Adding option --persistent  stores  any  combination  of  device
159              parameters  above  in  LUKS2  metadata  (only  after  successful
160              refresh operation).
161
162              --disable-keyring parameter refreshes a device with  volume  key
163              passed in dm-crypt driver.
164
165

PLAIN MODE

167       Plain dm-crypt encrypts the device sector-by-sector with a single, non-
168       salted hash of the passphrase. No checks are performed, no metadata  is
169       used.  There is no formatting operation.  When the raw device is mapped
170       (opened), the usual device operations can be used on the mapped device,
171       including  filesystem  creation.   Mapped  devices  usually  reside  in
172       /dev/mapper/<name>.
173
174       The following are valid plain device type actions:
175
176       open --type plain <device> <name>
177       create <name> <device> (OBSOLETE syntax)
178
179              Opens (creates a mapping with) <name> backed by device <device>.
180
181              <options> can be [--hash, --cipher, --verify-passphrase,  --sec‐
182              tor-size,  --key-file,  --keyfile-offset,  --key-size, --offset,
183              --skip,   --size,   --readonly,   --shared,    --allow-discards,
184              --refresh]
185
186              Example:  'cryptsetup  open --type plain /dev/sda10 e1' maps the
187              raw encrypted device /dev/sda10 to the mapped (decrypted) device
188              /dev/mapper/e1,  which  can  then  be mounted, fsck-ed or have a
189              filesystem created on it.
190

LUKS EXTENSION

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

loop-AES EXTENSION

551       cryptsetup  supports  mapping loop-AES encrypted partition using a com‐
552       patibility mode.
553
554       open --type loopaes <device> <name> --key-file <keyfile>
555       loopaesOpen <device> <name> --key-file <keyfile>  (old syntax)
556
557              Opens the loop-AES <device> and sets up a mapping <name>.
558
559              If the key file is encrypted with GnuPG, then you  have  to  use
560              --key-file=- and decrypt it before use, e.g. like this:
561              gpg  --decrypt  <keyfile>  | cryptsetup loopaesOpen --key-file=-
562              <device> <name>
563
564              WARNING: The loop-AES extension cannot use the direct  input  of
565              key file on real terminal because the keys are separated by end-
566              of-line and only part of the multi-key file would be read.
567              If you need it in script, just use the pipe redirection:
568              echo $keyfile |  cryptsetup  loopaesOpen  --key-file=-  <device>
569              <name>
570
571              Use --keyfile-size to specify the proper key length if needed.
572
573              Use  --offset to specify device offset. Note that the units need
574              to be specified in number of 512 byte sectors.
575
576              Use --skip to specify the IV offset. If the original device used
577              an  offset and but did not use it in IV sector calculations, you
578              have to explicitly use --skip 0 in addition to the offset param‐
579              eter.
580
581              Use  --hash to override the default hash function for passphrase
582              hashing (otherwise it is detected according to key size).
583
584              <options> can  be  [--key-file,  --key-size,  --offset,  --skip,
585              --hash, --readonly, --allow-discards, --refresh].
586
587       See  also  section 7 of the FAQ and http://loop-aes.sourceforge.net for
588       more information regarding loop-AES.
589

TCRYPT (TrueCrypt-compatible and VeraCrypt) EXTENSION

591       cryptsetup supports mapping of TrueCrypt,  tcplay  or  VeraCrypt  (with
592       --veracrypt  option)  encrypted  partition  using a native Linux kernel
593       API.  Header formatting and TCRYPT  header  change  is  not  supported,
594       cryptsetup never changes TCRYPT header on-device.
595
596       TCRYPT  extension  requires kernel userspace crypto API to be available
597       (introduced in Linux kernel 2.6.38).  If  you  are  configuring  kernel
598       yourself,  enable  "User-space interface for symmetric key cipher algo‐
599       rithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER  .con‐
600       fig option).
601
602       Because  TCRYPT  header  is encrypted, you have to always provide valid
603       passphrase and keyfiles.
604
605       Cryptsetup should recognize all header variants, except  legacy  cipher
606       chains  using LRW encryption mode with 64 bits encryption block (namely
607       Blowfish in LRW mode is not recognized, this is  limitation  of  kernel
608       crypto API).
609
610       To  recognize a VeraCrypt device use the --veracrypt option.  VeraCrypt
611       is just extension of TrueCrypt header with increased iteration count so
612       unlocking  can  take  quite  a  lot  of time (in comparison with TCRYPT
613       device).
614
615       To open a VeraCrypt device with a custom Personal Iteration  Multiplier
616       (PIM)  value,  additionally  to  --veracrypt   use  either  the  --ver‐
617       acrypt-pim=<PIM> option to directly specify the  PIM  on  the  command-
618       line or use --veracrypt-query-pim to be prompted for the PIM.
619
620       The  PIM  value  affects  the  number  of iterations applied during key
621       derivation.   Please    refer    to    https://www.veracrypt.fr/en/Per
622       sonal%20Iterations%20Multiplier%20%28PIM%29.html   for   more  detailed
623       information.
624
625       NOTE: Activation with tcryptOpen is supported only  for  cipher  chains
626       using LRW or XTS encryption modes.
627
628       The  tcryptDump  command  should work for all recognized TCRYPT devices
629       and doesn't require superuser privilege.
630
631       To map system device (device with boot loader where the whole encrypted
632       system  resides)  use  --tcrypt-system  option.   You can use partition
633       device as the parameter (parameter must be real partition  device,  not
634       an image in a file), then only this partition is mapped.
635
636       If you have the whole TCRYPT device as a file image and you want to map
637       multiple partition encrypted  with  system  encryption,  please  create
638       loopback  mapping with partitions first (losetup -P, see losetup(8) man
639       page for more info), and use loop partition as the device parameter.
640
641       If you use the whole base device as a parameter,  one  device  for  the
642       whole  system  encryption  is  mapped.  This mode is available only for
643       backward compatibility with  older  cryptsetup  versions  which  mapped
644       TCRYPT system encryption using the whole device.
645
646       To  use  hidden  header  (and  map  hidden  device,  if available), use
647       --tcrypt-hidden option.
648
649       To  explicitly  use  backup  (secondary)  header,  use  --tcrypt-backup
650       option.
651
652       NOTE: There is no protection for a hidden volume if the outer volume is
653       mounted. The reason is that if there  were  any  protection,  it  would
654       require  some  metadata  describing what to protect in the outer volume
655       and the hidden volume would become detectable.
656
657
658       open --type tcrypt <device> <name>
659       tcryptOpen <device> <name>  (old syntax)
660
661              Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a
662              mapping <name>.
663
664              <options>  can be [--key-file, --tcrypt-hidden, --tcrypt-system,
665              --tcrypt-backup,  --readonly,  --test-passphrase,   --allow-dis‐
666              cards, --veracrypt, --veracrypt-pim, --veracrypt-query-pim].
667
668              The  keyfile parameter allows a combination of file content with
669              the passphrase and can be repeated. Note that using keyfiles  is
670              compatible with TCRYPT and is different from LUKS keyfile logic.
671
672              WARNING:  Option --allow-discards cannot be combined with option
673              --tcrypt-hidden. For normal mapping, it can cause  the  destruc‐
674              tion of hidden volume (hidden volume appears as unused space for
675              outer volume so this space can be discarded).
676
677
678       tcryptDump <device>
679
680              Dump the header information of a TCRYPT device.
681
682              If the --dump-master-key option is used, the TCRYPT device  mas‐
683              ter key is dumped instead of TCRYPT header info. Beware that the
684              master key (or concatenated master keys if cipher chain is used)
685              can  be  used to decrypt the data stored in the TCRYPT container
686              without a passphrase.  This means that if the master key is com‐
687              promised,  the  whole device has to be erased to prevent further
688              access. Use this option carefully.
689
690              <options> can be [--dump-master-key,  --key-file,  --tcrypt-hid‐
691              den, --tcrypt-system, --tcrypt-backup].
692
693              The  keyfile parameter allows a combination of file content with
694              the passphrase and can be repeated.
695
696       See also https://en.wikipedia.org/wiki/TrueCrypt for  more  information
697       regarding TrueCrypt.
698
699       Please  note that cryptsetup does not use TrueCrypt code, please report
700       all problems related to this compatibility extension to the  cryptsetup
701       project.
702

MISCELLANEOUS

704       repair <device>
705
706              Tries  to repair the device metadata if possible. Currently sup‐
707              ported only for LUKS device type.
708
709              This command is useful to fix some known  benign  LUKS  metadata
710              header corruptions. Only basic corruptions of unused keyslot are
711              fixable. This command will only change the LUKS header, not  any
712              key-slot  data.  You  may  enforce LUKS version by adding --type
713              option.
714
715              WARNING: Always create a binary backup of  the  original  header
716              before calling this command.
717
718       benchmark <options>
719
720              Benchmarks  ciphers  and KDF (key derivation function).  Without
721              parameters, it tries to measure few common configurations.
722
723              To benchmark  other  ciphers  or  modes,  you  need  to  specify
724              --cipher and --key-size options or --hash for KDF test.
725
726              NOTE:  This  benchmark is using memory only and is only informa‐
727              tive.  You cannot directly predict real storage encryption speed
728              from it.
729
730              For  testing  block  ciphers,  this  benchmark  requires  kernel
731              userspace crypto API to be available (introduced in Linux kernel
732              2.6.38).   If you are configuring kernel yourself, enable "User-
733              space interface for symmetric key cipher algorithms" in "Crypto‐
734              graphic API" section (CRYPTO_USER_API_SKCIPHER .config option).
735
736              <options> can be [--cipher, --key-size, --hash].
737

OPTIONS

739       --verbose, -v
740              Print more information on command execution.
741
742       --debug or --debug-json
743              Run  in debug mode with full diagnostic logs. Debug output lines
744              are always prefixed by '#'.  If --debug-json is used, additional
745              LUKS2 JSON data structures are printed.
746
747       --type <device-type>
748              Specifies  required  device  type, for more info read BASIC COM‐
749              MANDS section.
750
751       --hash, -h <hash-spec>
752              Specifies the passphrase hash for open (for  plain  and  loopaes
753              device types).
754
755              Specifies  the hash used in the LUKS key setup scheme and volume
756              key digest for luksFormat. The specified hash is used  as  hash-
757              parameter for PBKDF2 and for the AF splitter.
758
759              The  specified  hash  name  is  passed to the compiled-in crypto
760              backend.  Different backends may support different hashes.   For
761              luksFormat, the hash algorithm must provide at least 160 bits of
762              output, which excludes, e.g., MD5. Do not use a non-crypto  hash
763              like "crc32" as this breaks security.
764
765              Values compatible with old version of cryptsetup are "ripemd160"
766              for open --type plain and "sha1" for luksFormat.
767
768              Use cryptsetup --help to show the defaults.
769
770       --cipher, -c <cipher-spec>
771              Set the cipher specification string.
772
773              cryptsetup --help shows the compiled-in defaults.   The  current
774              default in the distributed sources is "aes-cbc-essiv:sha256" for
775              plain dm-crypt and "aes-xts-plain64" for LUKS.
776
777              If a hash is part of the cipher specification, then it  is  used
778              as  part  of  the IV generation. For example, ESSIV needs a hash
779              function, while "plain64" does not and hence none is specified.
780
781              For XTS mode you can optionally set a key size of 512 bits  with
782              the  -s  option.  Key  size for XTS mode is twice that for other
783              modes for the same security level.
784
785              XTS mode requires kernel 2.6.24 or later  and  plain64  requires
786              kernel  2.6.33  or  later.  More information can be found in the
787              FAQ.
788
789       --verify-passphrase, -y
790              When interactively asking for a passphrase, ask for it twice and
791              complain  if  both  inputs do not match. Advised when creating a
792              regular mapping for the first time, or when running  luksFormat.
793              Ignored on input from file or stdin.
794
795       --key-file, -d name
796              Read the passphrase from file.
797
798              If  the name given is "-", then the passphrase will be read from
799              stdin.  In this case, reading will not stop at  newline  charac‐
800              ters.
801
802              With  LUKS,  passphrases  supplied via --key-file are always the
803              existing passphrases requested by a command, except in the  case
804              of  luksFormat  where --key-file is equivalent to the positional
805              key file argument.
806
807              If you want to set a new passphrase via key file,  you  have  to
808              use a positional argument to luksAddKey.
809
810              See section NOTES ON PASSPHRASE PROCESSING for more information.
811
812       --keyfile-offset value
813              Skip  value  bytes at the beginning of the key file.  Works with
814              all commands that accept key files.
815
816       --keyfile-size, -l value
817              Read a maximum of value bytes from the key file.  The default is
818              to read the whole file up to the compiled-in maximum that can be
819              queried with --help. Supplying more data  than  the  compiled-in
820              maximum aborts the operation.
821
822              This  option is useful to cut trailing newlines, for example. If
823              --keyfile-offset is also given, the size count starts after  the
824              offset.  Works with all commands that accept key files.
825
826       --new-keyfile-offset value
827              Skip  value bytes at the start when adding a new passphrase from
828              key file with luksAddKey.
829
830       --new-keyfile-size  value
831              Read a maximum of value bytes when adding a new passphrase  from
832              key file with luksAddKey.  The default is to read the whole file
833              up to the compiled-in maximum length that can  be  queried  with
834              --help.   Supplying more than the compiled in maximum aborts the
835              operation.  When --new-keyfile-offset  is  also  given,  reading
836              starts after the offset.
837
838       --master-key-file
839              Use a master key stored in a file.
840
841              For luksFormat this allows creating a LUKS header with this spe‐
842              cific master key. If the master key was taken from  an  existing
843              LUKS  header and all other parameters are the same, then the new
844              header decrypts the data encrypted with the  header  the  master
845              key was taken from.
846
847              Action luksDump together with --dump-master-key option: The vol‐
848              ume (master) key is stored in a file instead  of  being  printed
849              out to standard output.
850
851              WARNING:  If  you  create  your own master key, you need to make
852              sure to do it right. Otherwise, you  can  end  up  with  a  low-
853              entropy or otherwise partially predictable master key which will
854              compromise security.
855
856              For luksAddKey this allows adding a new passphrase without  hav‐
857              ing to know an existing one.
858
859              For  open this allows one to open the LUKS device without giving
860              a passphrase.
861
862       --dump-master-key
863              For luksDump this option includes the master  key  in  the  dis‐
864              played information. Use with care, as the master key can be used
865              to bypass the passphrases, see also option --master-key-file.
866
867       --json-file
868              Read token json from a file or write  token  to  it.  See  token
869              action for more information. --json-file=- reads json from stan‐
870              dard input or writes it to standard output respectively.
871
872       --use-random
873
874       --use-urandom
875              For luksFormat these options define which kernel  random  number
876              generator  will  be  used  to  create the master key (which is a
877              long-term key).
878
879              See NOTES ON RANDOM NUMBER GENERATORS for more information.  Use
880              cryptsetup  --help to show the compiled-in default random number
881              generator.
882
883              WARNING: In a low-entropy situation (e.g. in  an  embedded  sys‐
884              tem),  both  selections are problematic.  Using /dev/urandom can
885              lead to weak keys.  Using /dev/random can  block  a  long  time,
886              potentially  forever,  if not enough entropy can be harvested by
887              the kernel.
888
889       --key-slot, -S <0-7>
890              For LUKS operations that add key material, this  options  allows
891              you to specify which key slot is selected for the new key.  This
892              option can be used for luksFormat, and luksAddKey.
893              In addition, for open, this option selects a  specific  key-slot
894              to  compare  the  passphrase  against.   If the given passphrase
895              would only match a different key-slot, the operation fails.
896
897       --key-size, -s <bits>
898              Sets key size in bits. The argument has to be a multiple  of  8.
899              The possible key-sizes are limited by the cipher and mode used.
900
901              See  /proc/crypto  for  more  information. Note that key-size in
902              /proc/crypto is stated in bytes.
903
904              This option can be used for open  --type  plain  or  luksFormat.
905              All  other  LUKS  actions will use the key-size specified in the
906              LUKS header.  Use cryptsetup  --help  to  show  the  compiled-in
907              defaults.
908
909       --size, -b <number of 512 byte sectors>
910              Set the size of the device in sectors of 512 bytes.  This option
911              is only relevant for the open and resize actions.
912
913       --offset, -o <number of 512 byte sectors>
914              Start offset in the backend device in  512-byte  sectors.   This
915              option  is  only  relevant  for  the  open  action with plain or
916              loopaes device types or for LUKS devices in luksFormat.
917
918              For LUKS, the --offset option sets the data offset (payload)  of
919              data device and must be be aligned to 4096-byte sectors (must be
920              multiple  of  8).   This  option   cannot   be   combined   with
921              --align-payload option.
922
923       --skip, -p <number of 512 byte sectors>
924              Start  offset  used  in  IV calculation in 512-byte sectors (how
925              many sectors of the encrypted data to skip  at  the  beginning).
926              This  option  is only relevant for the open action with plain or
927              loopaes device types.
928
929              Hence, if --offset n, and --skip s, sector n (the  first  sector
930              of  the  encrypted device) will get a sector number of s for the
931              IV calculation.
932
933       --readonly, -r
934              set up a read-only mapping.
935
936       --shared
937              Creates an additional mapping for one common ciphertext  device.
938              Arbitrary  mappings are supported.  This option is only relevant
939              for the open --type  plain  action.  Use  --offset,  --size  and
940              --skip to specify the mapped area.
941
942       --pbkdf <PBKDF spec>
943              Set Password-Based Key Derivation Function (PBKDF) algorithm for
944              LUKS keyslot.  The PBKDF can be: pbkdf2 (for PBKDF2 according to
945              RFC2898),  argon2i  for  Argon2i  or  argon2id for Argon2id (see
946              https://www.cryptolux.org/index.php/Argon2 for more info).
947
948              For LUKS1, only PBKDF2 is accepted (no need to use this option).
949              The  default PBKDF2 for LUKS2 is set during compilation time and
950              is available in cryptsetup --help output.
951
952              A PBKDF is used for increasing dictionary and brute-force attack
953              cost  for  keyslot passwords. The parameters can be time, memory
954              and parallel cost.
955
956              For PBKDF2, only time cost (number of iterations) applies.   For
957              Argon2i/id,  there  is  also memory cost (memory required during
958              the process of key derivation)  and  parallel  cost  (number  of
959              threads that run in parallel during the key derivation.
960
961              Note  that  increasing  memory  cost also increases time, so the
962              final parameter values are measured by a benchmark.  The  bench‐
963              mark  tries  to  find iteration time (--iter-time) with required
964              memory cost --pbkdf-memory. If it is not  possible,  the  memory
965              cost  is  decreased as well.  The parallel cost --pbkdf-parallel
966              is constant, is is checked against available CPU cores  (if  not
967              available, it is decreased) and the maximum parallel cost is 4.
968
969              You  can  see  all PBKDF parameters for particular LUKS2 keyslot
970              with luksDump command.
971
972              NOTE: If you do not want to use benchmark and  want  to  specify
973              all   parameters  directly,  use  --pbkdf-force-iterations  with
974              --pbkdf-memory and --pbkdf-parallel.   This  will  override  the
975              values  without  benchmarking.  Note it can cause extremely long
976              unlocking time. Use only is specified cases, for example, if you
977              know that the formatted device will be used on some small embed‐
978              ded system.  In this case, the LUKS PBKDF2 digest will be set to
979              the minimum iteration count.
980
981       --iter-time, -i <number of milliseconds>
982              The  number  of milliseconds to spend with PBKDF passphrase pro‐
983              cessing.  This option is only relevant for LUKS operations  that
984              set  or  change  passphrases,  such as luksFormat or luksAddKey.
985              Specifying 0 as parameter selects the compiled-in default.
986
987       --pbkdf-memory <number>
988              Set the memory cost for PBKDF (for Argon2i/id the number  repre‐
989              sents  kilobytes).   Note that it is maximal value, PBKDF bench‐
990              mark or available physical memory can decrease it.  This  option
991              is not available for PBKDF2.
992
993       --pbkdf-parallel <number>
994              Set  the  parallel  cost for PBKDF (number of threads, up to 4).
995              Note that it is maximal value, it is decreased automatically  if
996              CPU  online  count  is  lower.  This option is not available for
997              PBKDF2.
998
999       --pbkdf-force-iterations <num>
1000              Avoid PBKDF benchmark and set time cost  (iterations)  directly.
1001              It  can  be used for LUKS/LUKS2 device only.  See --pbkdf option
1002              for more info.
1003
1004       --batch-mode, -q
1005              Suppresses all confirmation questions. Use with care!
1006
1007              If the -y option is not specified, this option also switches off
1008              the passphrase verification for luksFormat.
1009
1010       --progress-frequency <seconds>
1011              Print separate line every <seconds> with wipe progress.
1012
1013       --timeout, -t <number of seconds>
1014              The number of seconds to wait before timeout on passphrase input
1015              via terminal. It is relevant every time a passphrase  is  asked,
1016              for  example  for  open,  luksFormat  or  luksAddKey.  It has no
1017              effect if used in conjunction with --key-file.
1018              This option is useful when the system should not  stall  if  the
1019              user  does not input a passphrase, e.g. during boot. The default
1020              is a value of 0 seconds, which means to wait forever.
1021
1022       --tries, -T
1023              How often the input of the passphrase shall  be  retried.   This
1024              option is relevant every time a passphrase is asked, for example
1025              for open, luksFormat or luksAddKey.  The default is 3 tries.
1026
1027       --align-payload <number of 512 byte sectors>
1028              Align payload at a boundary of  value  512-byte  sectors.   This
1029              option is relevant for luksFormat.
1030
1031              If not specified, cryptsetup tries to use the topology info pro‐
1032              vided by the kernel for the underlying device to get the optimal
1033              alignment.   If not available (or the calculated value is a mul‐
1034              tiple of the default) data is  by  default  aligned  to  a  1MiB
1035              boundary (i.e. 2048 512-byte sectors).
1036
1037              For  a detached LUKS header, this option specifies the offset on
1038              the data device. See also the --header option.
1039
1040              WARNING: This option is  DEPRECATED  and  has  often  unexpected
1041              impact  to the data offset and keyslot area size (for LUKS2) due
1042              to the complex rounding.   For  fixed  data  device  offset  use
1043              --offset option instead.
1044
1045
1046       --uuid=UUID
1047              Use the provided UUID for the luksFormat command instead of gen‐
1048              erating a new one. Changes the existing UUID when used with  the
1049              luksUUID command.
1050
1051              The  UUID  must  be  provided  in the standard UUID format, e.g.
1052              12345678-1234-1234-1234-123456789abc.
1053
1054       --allow-discards
1055              Allow the use of discard (TRIM) requests for the  device.   This
1056              option is only relevant for open action.
1057
1058              WARNING:  This  command  can  have  a  negative  security impact
1059              because it can make filesystem-level operations visible  on  the
1060              physical  device.  For  example,  information leaking filesystem
1061              type, used space, etc. may  be  extractable  from  the  physical
1062              device  if  the  discarded  blocks  can  be located later. If in
1063              doubt, do not use it.
1064
1065              A kernel version of 3.1 or later is needed. For earlier kernels,
1066              this option is ignored.
1067
1068       --perf-same_cpu_crypt
1069              Perform  encryption using the same cpu that IO was submitted on.
1070              The default is to use an unbound workqueue  so  that  encryption
1071              work  is  automatically  balanced  between available CPUs.  This
1072              option is only relevant for open action.
1073
1074              NOTE: This option is available only for low-level dm-crypt  per‐
1075              formance  tuning,  use  only if you need a change to default dm-
1076              crypt behaviour. Needs kernel 4.0 or later.
1077
1078       --perf-submit_from_crypt_cpus
1079              Disable offloading writes to a separate thread after encryption.
1080              There  are  some situations where offloading write bios from the
1081              encryption threads to a single thread degrades performance  sig‐
1082              nificantly.   The  default  is to offload write bios to the same
1083              thread.  This option is only relevant for open action.
1084
1085              NOTE: This option is available only for low-level dm-crypt  per‐
1086              formance  tuning,  use  only if you need a change to default dm-
1087              crypt behaviour. Needs kernel 4.0 or later.
1088
1089       --test-passphrase
1090              Do not activate the device, just verify passphrase.  This option
1091              is only relevant for open action (the device mapping name is not
1092              mandatory if this option is used).
1093
1094       --header <device or file storing the LUKS header>
1095              Use a detached (separated) metadata device  or  file  where  the
1096              LUKS  header  is stored. This option allows one to store cipher‐
1097              text and LUKS header on different devices.
1098
1099              This option is only relevant for LUKS devices and  can  be  used
1100              with  the  luksFormat, open, luksSuspend, luksResume, status and
1101              resize commands.
1102
1103              For luksFormat with a file name as the argument to --header, the
1104              file  will  be  automatically created if it does not exist.  See
1105              the cryptsetup FAQ for header size calculation.
1106
1107              For other commands that change the LUKS  header  (e.g.  luksAdd‐
1108              Key),  specify  the device or file with the LUKS header directly
1109              as the LUKS device.
1110
1111              If used with luksFormat, the --align-payload option is taken  as
1112              absolute sector alignment on ciphertext device and can be zero.
1113
1114              WARNING:  There is no check whether the ciphertext device speci‐
1115              fied actually belongs to the header  given.  In  fact,  you  can
1116              specify  an  arbitrary  device as the ciphertext device for open
1117              with the --header option. Use with care.
1118
1119       --header-backup-file <file>
1120              Specify file with header backup  for  luksHeaderBackup  or  luk‐
1121              sHeaderBackup actions.
1122
1123       --force-password
1124              Do not use password quality checking for new LUKS passwords.
1125
1126              This   option   applies   only  to  luksFormat,  luksAddKey  and
1127              luksChangeKey and is ignored  if  cryptsetup  is  built  without
1128              password quality checking support.
1129
1130              For  more info about password quality check, see the manual page
1131              for pwquality.conf(5) and passwdqc.conf(5).
1132
1133       --deferred
1134              Defers device removal in  close  command  until  the  last  user
1135              closes it.
1136
1137       --disable-locks
1138              Disable  lock  protection  for metadata on disk.  This option is
1139              valid only for LUKS2 and ignored for other formats.
1140
1141              WARNING: Do not use this option unless you run cryptsetup  in  a
1142              restricted  environment  where  locking is impossible to perform
1143              (where /run directory cannot be used).
1144
1145       --disable-keyring
1146              Do not load volume key in  kernel  keyring  but  use  store  key
1147              directly  in the dm-crypt target.  This option is supported only
1148              for the LUKS2 format.
1149
1150       --key-description <text>
1151              Set key description in keyring for use with token command.
1152
1153       --priority <normal|prefer|ignore>
1154              Set a priority for LUKS2 keyslot.  The  prefer  priority  marked
1155              slots  are  tried  before normal priority.  The ignored priority
1156              means, that slot is never used, if not explicitly  requested  by
1157              --key-slot option.
1158
1159       --token-id
1160              Specify  what token to use in actions token, open or resize.  If
1161              omitted, all available tokens will be checked before  proceeding
1162              further with passphrase prompt.
1163
1164       --token-only
1165              Do  not  proceed  further  with  action  (any  of token, open or
1166              resize) if token activation failed. Without the  option,  action
1167              asks for passphrase to proceed further.
1168
1169       --sector-size <bytes>
1170              Set  sector  size for use with disk encryption. It must be power
1171              of two and in range 512 - 4096 bytes. The default is  512  bytes
1172              sectors.  This option is available only in the LUKS2 mode.
1173
1174              Note  that if sector size is higher than underlying device hard‐
1175              ware sector and there is not integrity protection that uses data
1176              journal,  using this option can increase risk on incomplete sec‐
1177              tor writes during a power fail.
1178
1179              If used together with --integrity option and dm-integrity  jour‐
1180              nal,  the atomicity of writes is guaranteed in all cases (but it
1181              cost write performance - data has to be written twice).
1182
1183              Increasing sector size from 512 bytes to 4096 bytes can  provide
1184              better  performance  on  most  of the modern storage devices and
1185              also with some hw encryption accelerators.
1186
1187       --persistent
1188              If used with LUKS2 devices and activation  commands  like  open,
1189              the  specified  activation  flags  are persistently written into
1190              metadata and used next time automatically even for normal  acti‐
1191              vation.   (No  need to use cryptab or other system configuration
1192              files.)     Only    --allow-discards,     --perf-same_cpu_crypt,
1193              --perf-submit_from_crypt_cpus  and --integrity-no-journal can be
1194              stored persistently.
1195
1196       --refresh
1197              Refreshes an active device  with  new  set  of  parameters.  See
1198              action refresh description for more details.
1199
1200       --label <LABEL>
1201              --subsystem  <SUBSYSTEM> Set label and subsystem description for
1202              LUKS2 device, can be used in config  and  format  actions.   The
1203              label and subsystem are optional fields and can be later used in
1204              udev scripts for triggering user actions once device  marked  by
1205              these labels is detected.
1206
1207       --integrity <integrity algorithm>
1208              Specify  integrity  algorithm  to be used for authenticated disk
1209              encryption in LUKS2.
1210
1211              WARNING:  This  extension  is  EXPERIMENTAL  and  requires   dm-
1212              integrity  kernel  target (available since kernel version 4.12).
1213              For native AEAD modes, also  enable  "User-space  interface  for
1214              AEAD  cipher  algorithms"  in  "Cryptographic API" section (CON‐
1215              FIG_CRYPTO_USER_API_AEAD .config option).
1216
1217              For more info, see AUTHENTICATED DISK ENCRYPTION section.
1218
1219       --luks2-metadata-size <size>
1220              This option can be used to enlarge  the  LUKS2  metadata  (JSON)
1221              area.   The size includes 4096 bytes for binary metadata (usable
1222              JSON area is smaller of the binary area).   According  to  LUKS2
1223              specification,  only  these  values  are valid: 16, 32, 64, 128,
1224              256, 512, 1024, 2048 and 4096 kB The  <size>  can  be  specified
1225              with unit suffix (for example 128k).
1226
1227       --luks2-keyslots-size <size>
1228              This option can be used to set specific size of the LUKS2 binary
1229              keyslot area (key material is encrypted there). The  value  must
1230              be  aligned  to  multiple of 4096 bytes with maximum size 128MB.
1231              The <size> can be specified with unit suffix (for example 128k).
1232
1233       --keyslot-cipher <cipher-spec>
1234              This option can be used to set specific  cipher  encryption  for
1235              the LUKS2 keyslot area.
1236
1237       --keyslot-key-size <bits>
1238              This  option  can be used to set specific key size for the LUKS2
1239              keyslot area.
1240
1241       --integrity-no-journal
1242              Activate device with integrity  protection  without  using  data
1243              journal  (direct  write  of data and integrity tags).  Note that
1244              without journal power fail can cause non-atomic write  and  data
1245              corruption.  Use only if journalling is performed on a different
1246              storage layer.
1247
1248       --integrity-no-wipe
1249              Skip wiping of device authentication (integrity)  tags.  If  you
1250              skip  this step, sectors will report invalid integrity tag until
1251              an application write to the sector.
1252
1253              NOTE: Even some writes to the device can fail if  the  write  is
1254              not aligned to page size and page-cache initiates read of a sec‐
1255              tor with invalid integrity tag.
1256
1257       --unbound
1258
1259              Creates new LUKS2 unbound keyslot.  See  luksAddKey  action  for
1260              more details.
1261
1262       --tcrypt-hidden
1263              --tcrypt-system  --tcrypt-backup Specify which TrueCrypt on-disk
1264              header will be used to open the device.  See TCRYPT section  for
1265              more info.
1266
1267       --veracrypt
1268              Allow VeraCrypt compatible mode. Only for TCRYPT extension.  See
1269              TCRYPT section for more info.
1270
1271       --veracrypt-pim
1272              --veracrypt-query-pim Use a custom Personal Iteration Multiplier
1273              (PIM) for VeraCrypt device.  See TCRYPT section for more info.
1274
1275       --version
1276              Show the program version.
1277
1278       --usage
1279              Show short option help.
1280
1281       --help, -?
1282              Show help text and default parameters.
1283

RETURN CODES

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

NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE

1292       Note  that  no  iterated  hashing or salting is done in plain mode.  If
1293       hashing is done, it is a single  direct  hash.  This  means  that  low-
1294       entropy passphrases are easy to attack in plain mode.
1295
1296       From  a  terminal: The passphrase is read until the first newline, i.e.
1297       '\n'.  The input without the newline character is  processed  with  the
1298       default  hash  or the hash specified with --hash.  The hash result will
1299       be truncated to the key size of the used cipher, or the size  specified
1300       with -s.
1301
1302       From stdin: Reading will continue until a newline (or until the maximum
1303       input size is reached), with the trailing newline stripped. The maximum
1304       input  size is defined by the same compiled-in default as for the maxi‐
1305       mum key file size and can be overwritten using --keyfile-size option.
1306
1307       The data read will be hashed with the default hash or the  hash  speci‐
1308       fied with --hash.  The hash result will be truncated to the key size of
1309       the used cipher, or the size specified with -s.
1310
1311       Note that if --key-file=- is used  for  reading  the  key  from  stdin,
1312       trailing newlines are not stripped from the input.
1313
1314       If  "plain"  is  used as argument to --hash, the input data will not be
1315       hashed. Instead, it will be zero padded (if shorter than the key  size)
1316       or  truncated  (if  longer  than the key size) and used directly as the
1317       binary key. This is useful for directly specifying a  binary  key.   No
1318       warning  will  be  given  if the amount of data read from stdin is less
1319       than the key size.
1320
1321       From a key file: It will be truncated to  the  key  size  of  the  used
1322       cipher or the size given by -s and directly used as a binary key.
1323
1324       WARNING:  The  --hash  argument is being ignored.  The --hash option is
1325       usable only for stdin input in plain mode.
1326
1327       If the key file is shorter than the key, cryptsetup will quit  with  an
1328       error.   The  maximum  input  size  is  defined by the same compiled-in
1329       default as for the maximum key file size and can be  overwritten  using
1330       --keyfile-size option.
1331
1332
1333

NOTES ON PASSPHRASE PROCESSING FOR LUKS

1335       LUKS uses PBKDF2 to protect against dictionary attacks and to give some
1336       protection to low-entropy passphrases (see RFC 2898 and the  cryptsetup
1337       FAQ).
1338
1339       From  a  terminal:  The  passphrase is read until the first newline and
1340       then processed by PBKDF2 without the newline character.
1341
1342       From stdin: LUKS will read passphrases from stdin up to the first  new‐
1343       line  character  or  the compiled-in maximum key file length. If --key‐
1344       file-size is given, it is ignored.
1345
1346       From key file: The complete keyfile is read up to the compiled-in maxi‐
1347       mum  size.  Newline  characters  do not terminate the input. The --key‐
1348       file-size option can be used to limit what is read.
1349
1350       Passphrase processing: Whenever a passphrase is added to a LUKS  header
1351       (luksAddKey,  luksFormat),  the  user may specify how much the time the
1352       passphrase processing should consume. The time is used to determine the
1353       iteration  count  for PBKDF2 and higher times will offer better protec‐
1354       tion for low-entropy passphrases, but open will  take  longer  to  com‐
1355       plete.  For  passphrases  that  have  entropy  higher than the used key
1356       length, higher iteration times will not increase security.
1357
1358       The default setting of one or two seconds is sufficient for most  prac‐
1359       tical  cases.  The only exception is a low-entropy passphrase used on a
1360       device with a slow CPU, as this will result in a low  iteration  count.
1361       On  a  slow  device, it may be advisable to increase the iteration time
1362       using the --iter-time option in order  to  obtain  a  higher  iteration
1363       count. This does slow down all later luksOpen operations accordingly.
1364

INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS

1366       LUKS  checks  for  a  valid  passphrase  when an encrypted partition is
1367       unlocked. The behavior of plain dm-crypt is different.  It will  always
1368       decrypt  with  the  passphrase given. If the given passphrase is wrong,
1369       the device mapped by plain  dm-crypt  will  essentially  still  contain
1370       encrypted data and will be unreadable.
1371

NOTES ON SUPPORTED CIPHERS, MODES, HASHES AND KEY SIZES

1373       The  available  combinations  of  ciphers,  modes, hashes and key sizes
1374       depend on kernel support. See /proc/crypto  for  a  list  of  available
1375       options.  You  might  need  to load additional kernel crypto modules in
1376       order to get more options.
1377
1378       For the --hash option, if the crypto backend  is  libgcrypt,  then  all
1379       algorithms  supported  by  the gcrypt library are available.  For other
1380       crypto backends, some algorithms may be missing.
1381

NOTES ON PASSPHRASES

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

NOTES ON RANDOM NUMBER GENERATORS

1391       Random Number Generators (RNG) used in cryptsetup are always the kernel
1392       RNGs without any modifications or additions to data stream produced.
1393
1394       There are two types  of  randomness  cryptsetup/LUKS  needs.  One  type
1395       (which always uses /dev/urandom) is used for salts, the AF splitter and
1396       for wiping deleted keyslots.
1397
1398       The second type is used for the volume (master)  key.  You  can  switch
1399       between  using /dev/random and /dev/urandom  here, see --use-random and
1400       --use-urandom options. Using /dev/random on  a  system  without  enough
1401       entropy  sources  can  cause  luksFormat  to  block until the requested
1402       amount of random data is gathered. In a low-entropy situation (embedded
1403       system), this can take a very long time and potentially forever. At the
1404       same time, using /dev/urandom in a low-entropy situation  will  produce
1405       low-quality  keys.  This is a serious problem, but solving it is out of
1406       scope for a mere man-page.  See urandom(4) for more information.
1407

AUTHENTICATED DISK ENCRYPTION (EXPERIMENTAL)

1409       Since Linux kernel version 4.12 dm-crypt  supports  authenticated  disk
1410       encryption.
1411
1412       Normal disk encryption modes are length-preserving (plaintext sector is
1413       of the same size as a ciphertext sector) and can provide only confiden‐
1414       tiality protection, but not cryptographically sound data integrity pro‐
1415       tection.
1416
1417       Authenticated modes require additional space per-sector for authentica‐
1418       tion  tag  and use Authenticated Encryption with Additional Data (AEAD)
1419       algorithms.
1420
1421       If you configure LUKS2 device with  data  integrity  protection,  there
1422       will  be  an  underlying dm-integrity device, which provides additional
1423       per-sector metadata space and also provide data journal  protection  to
1424       ensure  atomicity  of  data and metadata update.  Because there must be
1425       additional space for metadata and journal, the available space for  the
1426       device will be smaller than for length-preserving modes.
1427
1428       The  dm-crypt device then resides on top of such a dm-integrity device.
1429       All activation and deactivation of this device stack  is  performed  by
1430       cryptsetup, there is no difference in using luksOpen for integrity pro‐
1431       tected devices.  If you want to format LUKS2 device with data integrity
1432       protection, use --integrity option.
1433
1434       Some  integrity modes requires two independent keys (key for encryption
1435       and for authentication).  Both  these  keys  are  stored  in  one  LUKS
1436       keyslot.
1437
1438       WARNING:  All support for authenticated modes is experimental and there
1439       are only some modes available for now. Note that there are a  very  few
1440       authenticated  encryption algorithms that are suitable for disk encryp‐
1441       tion.
1442
1443

NOTES ON LOOPBACK DEVICE USE

1445       Cryptsetup is usually used directly on a block device  (disk  partition
1446       or  LVM  volume). However, if the device argument is a file, cryptsetup
1447       tries to allocate a loopback device and map it  into  this  file.  This
1448       mode  requires  Linux  kernel  2.6.25 or more recent which supports the
1449       loop autoclear flag (loop device is cleared on the last close automati‐
1450       cally). Of course, you can always map a file to a loop-device manually.
1451       See the cryptsetup FAQ for an example.
1452
1453       When device mapping is active, you can see the loop backing file in the
1454       status command output. Also see losetup(8).
1455

LUKS2 header locking

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

DEPRECATED ACTIONS

1466       The reload action is no longer supported.  Please use dmsetup(8) if you
1467       need to directly manipulate with the device mapping table.
1468
1469       The luksDelKey was replaced with luksKillSlot.
1470

REPORTING BUGS

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

AUTHORS

1478       cryptsetup originally written by Jana Saout <jana@saout.de>
1479       The LUKS extensions and original man page were written by Clemens Fruh‐
1480       wirth <clemens@endorphin.org>.
1481       Man page extensions by Milan Broz <gmazyland@gmail.com>.
1482       Man page rewrite and extension by Arno Wagner <arno@wagner.name>.
1483
1485       Copyright © 2004 Jana Saout
1486       Copyright © 2004-2006 Clemens Fruhwirth
1487       Copyright © 2012-2014 Arno Wagner
1488       Copyright © 2009-2019 Red Hat, Inc.
1489       Copyright © 2009-2019 Milan Broz
1490
1491       This is free software; see the source for copying conditions.  There is
1492       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
1493       PURPOSE.
1494

SEE ALSO

1496       The LUKS website at https://gitlab.com/cryptsetup/cryptsetup/
1497
1498       The cryptsetup FAQ, contained in the distribution package and online at
1499       https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
1500
1501       The cryptsetup mailing list and list archive, see FAQ entry 1.6.
1502
1503       The   LUKS  on-disk  format  specification  available  at  https://git
1504       lab.com/cryptsetup/cryptsetup/wikis/Specification
1505
1506
1507
1508cryptsetup                       January 2019                    CRYPTSETUP(8)
Impressum