1CRYPTSETUP(8) Maintenance Commands CRYPTSETUP(8)
2
3
4
6 cryptsetup - manage plain dm-crypt, LUKS, and other encrypted volumes
7
9 cryptsetup <action> [<options>] <action args>
10
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
19 loop-AES volumes, TrueCrypt, VeraCrypt, BitLocker and FileVault2
20 compatible volumes.
21
22 For more information about specific cryptsetup action see
23 cryptsetup-<action>[22m(8), where <action> is the name of the cryptsetup
24 action.
25
27 The following are valid actions for all supported device types.
28
29 OPEN
30 open <device> <name> --type <device_type>
31
32 Opens (creates a mapping with) <name> backed by device <device>.
33 See cryptsetup-open(8).
34
35 CLOSE
36 close <name>
37
38 Removes the existing mapping <name> and wipes the key from kernel
39 memory.
40 See cryptsetup-close(8).
41
42 STATUS
43 status <name>
44
45 Reports the status for the mapping <name>.
46 See cryptsetup-status(8).
47
48 RESIZE
49 resize <name>
50
51 Resizes an active mapping <name>.
52 See cryptsetup-resize(8).
53
54 REFRESH
55 refresh <name>
56
57 Refreshes parameters of active mapping <name>.
58 See cryptsetup-refresh(8).
59
60 REENCRYPT
61 reencrypt <device> or --active-name <name> [<new_name>]
62
63 Run LUKS device reencryption.
64 See cryptsetup-reencrypt(8).
65
67 Plain dm-crypt encrypts the device sector-by-sector with a single,
68 non-salted hash of the passphrase. No checks are performed, no metadata
69 is used. There is no formatting operation. When the raw device is
70 mapped (opened), the usual device operations can be used on the mapped
71 device, including filesystem creation. Mapped devices usually reside in
72 /dev/mapper/<name>.
73
74 The following are valid plain device type actions:
75
76 OPEN
77 open --type plain <device> <name>
78 create <name> <device> (OBSOLETE syntax)
79
80 Opens (creates a mapping with) <name> backed by device <device>.
81 See cryptsetup-open(8).
82
84 LUKS, the Linux Unified Key Setup, is a standard for disk encryption.
85 It adds a standardized header at the start of the device, a key-slot
86 area directly behind the header and the bulk data area behind that. The
87 whole set is called a 'LUKS container'. The device that a LUKS
88 container resides on is called a 'LUKS device'. For most purposes, both
89 terms can be used interchangeably. But note that when the LUKS header
90 is at a nonzero offset in a device, then the device is not a LUKS
91 device anymore, but has a LUKS container stored in it at an offset.
92
93 LUKS can manage multiple passphrases that can be individually revoked
94 or changed and that can be securely scrubbed from persistent media due
95 to the use of anti-forensic stripes. Passphrases are protected against
96 brute-force and dictionary attacks by Password-Based Key Derivation
97 Function (PBKDF).
98
99 LUKS2 is a new version of header format that allows additional
100 extensions like different PBKDF algorithm or authenticated encryption.
101 You can format device with LUKS2 header if you specify --type luks2 in
102 luksFormat command. For activation, the format is already recognized
103 automatically.
104
105 Each passphrase, also called a key in this document, is associated with
106 one of 8 key-slots. Key operations that do not specify a slot affect
107 the first slot that matches the supplied passphrase or the first empty
108 slot if a new passphrase is added.
109
110 The <device> parameter can also be specified by a LUKS UUID in the
111 format UUID=<uuid>. Translation to real device name uses symlinks in
112 /dev/disk/by-uuid directory.
113
114 To specify a detached header, the --header parameter can be used in all
115 LUKS commands and always takes precedence over the positional <device>
116 parameter.
117
118 The following are valid LUKS actions:
119
120 FORMAT
121 luksFormat <device> [<key file>]
122
123 Initializes a LUKS partition and sets the initial passphrase (for
124 key-slot 0).
125 See cryptsetup-luksFormat(8).
126
127 OPEN
128 open --type luks <device> <name>
129 luksOpen <device> <name> (old syntax)
130
131 Opens the LUKS device <device> and sets up a mapping <name> after
132 successful verification of the supplied passphrase.
133 See cryptsetup-open(8).
134
135 SUSPEND
136 luksSuspend <name>
137
138 Suspends an active device (all IO operations will block and accesses to
139 the device will wait indefinitely) and wipes the encryption key from
140 kernel memory.
141 See cryptsetup-luksSuspend(8).
142
143 RESUME
144 luksResume <name>
145
146 Resumes a suspended device and reinstates the encryption key.
147 See cryptsetup-luksResume(8).
148
149 ADD KEY
150 luksAddKey <device> [<key file with new key>]
151
152 Adds a new passphrase using an existing passphrase.
153 See cryptsetup-luksAddKey(8).
154
155 REMOVE KEY
156 luksRemoveKey <device> [<key file with passphrase to be removed>]
157
158 Removes the supplied passphrase from the LUKS device.
159 See cryptsetup-luksRemoveKey(8).
160
161 CHANGE KEY
162 luksChangeKey <device> [<new key file>]
163
164 Changes an existing passphrase.
165 See cryptsetup-luksChangeKey(8).
166
167 CONVERT KEY
168 luksConvertKey <device>
169
170 Converts an existing LUKS2 keyslot to new PBKDF parameters.
171 See cryptsetup-luksConvertKey(8).
172
173 KILL SLOT
174 luksKillSlot <device> <key slot number>
175
176 Wipe the key-slot number <key slot> from the LUKS device.
177 See cryptsetup-luksKillSlot(8).
178
179 ERASE
180 erase <device>
181 luksErase <device> (old syntax)
182
183 Erase all keyslots and make the LUKS container permanently
184 inaccessible.
185 See cryptsetup-erase(8).
186
187 UUID
188 luksUUID <device>
189
190 Print or set the UUID of a LUKS device.
191 See cryptsetup-luksUUID(8).
192
193 IS LUKS
194 isLuks <device>
195
196 Returns true, if <device> is a LUKS device, false otherwise.
197 See cryptsetup-isLuks(8).
198
199 DUMP
200 luksDump <device>
201
202 Dump the header information of a LUKS device.
203 See cryptsetup-luksDump(8).
204
205 HEADER BACKUP
206 luksHeaderBackup <device> --header-backup-file <file>
207
208 Stores a binary backup of the LUKS header and keyslot area.
209 See cryptsetup-luksHeaderBackup(8).
210
211 HEADER RESTORE
212 luksHeaderRestore <device> --header-backup-file <file>
213
214 Restores a binary backup of the LUKS header and keyslot area from the
215 specified file.
216 See cryptsetup-luksHeaderRestore(8).
217
218 TOKEN
219 token <add|remove|import|export> <device>
220
221 Manipulate token objects used for obtaining passphrases.
222 See cryptsetup-token(8).
223
224 CONVERT
225 convert <device> --type <format>
226
227 Converts the device between LUKS1 and LUKS2 format (if possible).
228 See cryptsetup-convert(8).
229
230 CONFIG
231 config <device>
232
233 Set permanent configuration options (store to LUKS header).
234 See cryptsetup-config(8).
235
237 cryptsetup supports mapping loop-AES encrypted partition using a
238 compatibility mode.
239
240 OPEN
241 open --type loopaes <device> <name> --key-file <keyfile>
242 loopaesOpen <device> <name> --key-file <keyfile> (old syntax)
243
244 Opens the loop-AES <device> and sets up a mapping <name>.
245 See cryptsetup-open(8).
246
247 See also section 7 of the FAQ and loop-AES
248 <http://loop-aes.sourceforge.net> for more information regarding
249 loop-AES.
250
252 cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt encrypted
253 partition using a native Linux kernel API. Header formatting and TCRYPT
254 header change is not supported, cryptsetup never changes TCRYPT header
255 on-device.
256
257 TCRYPT extension requires kernel userspace crypto API to be available
258 (introduced in Linux kernel 2.6.38). If you are configuring kernel
259 yourself, enable "User-space interface for symmetric key cipher
260 algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER
261 .config option).
262
263 Because TCRYPT header is encrypted, you have to always provide valid
264 passphrase and keyfiles.
265
266 Cryptsetup should recognize all header variants, except legacy cipher
267 chains using LRW encryption mode with 64 bits encryption block (namely
268 Blowfish in LRW mode is not recognized, this is limitation of kernel
269 crypto API).
270
271 VeraCrypt is extension of TrueCrypt header with increased iteration
272 count so unlocking can take quite a lot of time.
273
274 To open a VeraCrypt device with a custom Personal Iteration Multiplier
275 (PIM) value, use either the --veracrypt-pim=<PIM> option to directly
276 specify the PIM on the command- line or use --veracrypt-query-pim to be
277 prompted for the PIM.
278
279 The PIM value affects the number of iterations applied during key
280 derivation. Please refer to PIM
281 <https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html>
282 for more detailed information.
283
284 If you need to disable VeraCrypt device support, use
285 --disable-veracrypt option.
286
287 NOTE: Activation with tcryptOpen is supported only for cipher chains
288 using LRW or XTS encryption modes.
289
290 The tcryptDump command should work for all recognized TCRYPT devices
291 and doesn’t require superuser privilege.
292
293 To map system device (device with boot loader where the whole encrypted
294 system resides) use --tcrypt-system option. You can use partition
295 device as the parameter (parameter must be real partition device, not
296 an image in a file), then only this partition is mapped.
297
298 If you have the whole TCRYPT device as a file image and you want to map
299 multiple partition encrypted with system encryption, please create
300 loopback mapping with partitions first (losetup -P, see losetup(8) man
301 page for more info), and use loop partition as the device parameter.
302
303 If you use the whole base device as a parameter, one device for the
304 whole system encryption is mapped. This mode is available only for
305 backward compatibility with older cryptsetup versions which mapped
306 TCRYPT system encryption using the whole device.
307
308 To use hidden header (and map hidden device, if available), use
309 --tcrypt-hidden option.
310
311 To explicitly use backup (secondary) header, use --tcrypt-backup
312 option.
313
314 NOTE: There is no protection for a hidden volume if the outer volume is
315 mounted. The reason is that if there were any protection, it would
316 require some metadata describing what to protect in the outer volume
317 and the hidden volume would become detectable.
318
319 OPEN
320 open --type tcrypt <device> <name>
321 tcryptOpen_ <device> <name> (old syntax)
322
323 Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a
324 mapping <name>.
325 See cryptsetup-open(8).
326
327 DUMP
328 tcryptDump <device>
329
330 Dump the header information of a TCRYPT device.
331 See cryptsetup-tcryptDump(8).
332
333 See also TrueCrypt <https://en.wikipedia.org/wiki/TrueCrypt> and
334 VeraCrypt <https://en.wikipedia.org/wiki/VeraCrypt> pages for more
335 information.
336
337 Please note that cryptsetup does not use TrueCrypt or VeraCrypt code,
338 please report all problems related to this compatibility extension to
339 the cryptsetup project.
340
342 cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted
343 partition using a native Linux kernel API. Header formatting and BITLK
344 header changes are not supported, cryptsetup never changes BITLK header
345 on-device.
346
347 BITLK extension requires kernel userspace crypto API to be available
348 (for details see TCRYPT section).
349
350 Cryptsetup should recognize all BITLK header variants, except legacy
351 header used in Windows Vista systems and partially decrypted BitLocker
352 devices. Activation of legacy devices encrypted in CBC mode requires at
353 least Linux kernel version 5.3 and for devices using Elephant diffuser
354 kernel 5.6.
355
356 The bitlkDump command should work for all recognized BITLK devices and
357 doesn’t require superuser privilege.
358
359 For unlocking with the open a password or a recovery passphrase or a
360 startup key must be provided.
361
362 Additionally unlocking using volume key is supported. You must provide
363 BitLocker Full Volume Encryption Key (FVEK) using the --volume-key-file
364 option. The key must be decrypted and without the header (only
365 128/256/512 bits of key data depending on used cipher and mode).
366
367 Other unlocking methods (TPM, SmartCard) are not supported.
368
369 OPEN
370 open --type bitlk <device> <name>
371 bitlkOpen <device> <name> (old syntax)
372
373 Opens the BITLK (a BitLocker-compatible) <device> and sets up a mapping
374 <name>.
375 See cryptsetup-open(8).
376
377 DUMP
378 bitlkDump <device>
379
380 Dump the header information of a BITLK device.
381 See cryptsetup-bitlkDump(8).
382
383 Please note that cryptsetup does not use any Windows BitLocker code,
384 please report all problems related to this compatibility extension to
385 the cryptsetup project.
386
388 cryptsetup supports the mapping of FileVault2 (FileVault2 full-disk
389 encryption) by Apple for the macOS operating system using a native
390 Linux kernel API.
391
392 NOTE: cryptsetup supports only FileVault2 based on Core Storage and
393 HFS+ filesystem (introduced in MacOS X 10.7 Lion). It does NOT support
394 the new version of FileVault based on the APFS filesystem used in
395 recent macOS versions.
396
397 Header formatting and FVAULT2 header changes are not supported;
398 cryptsetup never changes the FVAULT2 header on-device.
399
400 FVAULT2 extension requires kernel userspace crypto API to be available
401 (for details, see TCRYPT section) and kernel driver for HFS+ (hfsplus)
402 filesystem.
403
404 Cryptsetup should recognize the basic configuration for portable
405 drives.
406
407 The fvault2Dump command should work for all recognized FVAULT2 devices
408 and doesn’t require superuser privilege.
409
410 For unlocking with the open, a password must be provided. Other
411 unlocking methods are not supported.
412
413 OPEN
414 open --type fvault2 <device> <name>
415 fvault2Open <device> <name> (old syntax)
416
417 Opens the FVAULT2 (a FileVault2-compatible) <device> (usually the
418 second partition on the device) and sets up a mapping <name>.
419 See cryptsetup-open(8).
420
421 DUMP
422 fvault2Dump <device>
423
424 Dump the header information of an FVAULT2 device.
425 See cryptsetup-fvault2Dump(8).
426
427 Note that cryptsetup does not use any macOS code or proprietary
428 specifications. Please report all problems related to this
429 compatibility extension to the cryptsetup project.
430
432 REPAIR
433 repair <device>
434
435 Tries to repair the device metadata if possible. Currently supported
436 only for LUKS device type.
437 See cryptsetup-repair(8).
438
439 BENCHMARK
440 benchmark <options>
441
442 Benchmarks ciphers and KDF (key derivation function).
443 See cryptsetup-benchmark(8).
444
446 Unless you understand the cryptographic background well, use LUKS. With
447 plain dm-crypt there are a number of possible user errors that
448 massively decrease security. While LUKS cannot fix them all, it can
449 lessen the impact for many of them.
450
452 A lot of good information on the risks of using encrypted storage, on
453 handling problems and on security aspects can be found in the
454 Cryptsetup FAQ. Read it. Nonetheless, some risks deserve to be
455 mentioned here.
456
457 Backup: Storage media die. Encryption has no influence on that. Backup
458 is mandatory for encrypted data as well, if the data has any worth. See
459 the Cryptsetup FAQ for advice on how to do a backup of an encrypted
460 volume.
461
462 Character encoding: If you enter a passphrase with special symbols, the
463 passphrase can change depending on character encoding. Keyboard
464 settings can also change, which can make blind input hard or
465 impossible. For example, switching from some ASCII 8-bit variant to
466 UTF-8 can lead to a different binary encoding and hence different
467 passphrase seen by cryptsetup, even if what you see on the terminal is
468 exactly the same. It is therefore highly recommended to select
469 passphrase characters only from 7-bit ASCII, as the encoding for 7-bit
470 ASCII stays the same for all ASCII variants and UTF-8.
471
472 LUKS header: If the header of a LUKS volume gets damaged, all data is
473 permanently lost unless you have a header-backup. If a key-slot is
474 damaged, it can only be restored from a header-backup or if another
475 active key-slot with known passphrase is undamaged. Damaging the LUKS
476 header is something people manage to do with surprising frequency. This
477 risk is the result of a trade-off between security and safety, as LUKS
478 is designed for fast and secure wiping by just overwriting header and
479 key-slot area.
480
481 Previously used partitions: If a partition was previously used, it is a
482 very good idea to wipe filesystem signatures, data, etc. before
483 creating a LUKS or plain dm-crypt container on it. For a quick removal
484 of filesystem signatures, use wipefs(8). Take care though that this may
485 not remove everything. In particular, MD RAID signatures at the end of
486 a device may survive. It also does not remove data. For a full wipe,
487 overwrite the whole partition before container creation. If you do not
488 know how to do that, the cryptsetup FAQ describes several options.
489
491 Example 1: Create LUKS 2 container on block device /dev/sdX.
492 sudo cryptsetup --type luks2 luksFormat /dev/sdX
493
494 Example 2: Add an additional passphrase to key slot 5.
495 sudo cryptsetup luksAddKey --key-slot 5 /dev/sdX
496
497 Example 3: Create LUKS header backup and save it to file.
498 sudo cryptsetup luksHeaderBackup /dev/sdX --header-backup-file
499 /var/tmp/NameOfBackupFile
500
501 Example 4: Open LUKS container on /dev/sdX and map it to sdX_crypt.
502 sudo cryptsetup open /dev/sdX sdX_crypt
503
504 WARNING: The command in example 5 will erase all key slots.
505 Your cannot use your LUKS container afterward anymore unless you
506 have a backup to restore.
507
508 Example 5: Erase all key slots on /dev/sdX.
509 sudo cryptsetup erase /dev/sdX
510
511 Example 6: Restore LUKS header from backup file.
512 sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file
513 /var/tmp/NameOfBackupFile
514
516 Cryptsetup returns 0 on success and a non-zero value on error.
517
518 Error codes are: 1 wrong parameters, 2 no permission (bad passphrase),
519 3 out of memory, 4 wrong device specified, 5 device already exists or
520 device is busy.
521
523 Passphrase processing for PLAIN mode
524 Note that no iterated hashing or salting is done in plain mode. If
525 hashing is done, it is a single direct hash. This means that
526 low-entropy passphrases are easy to attack in plain mode.
527
528 From a terminal: The passphrase is read until the first newline, i.e.
529 '\n'. The input without the newline character is processed with the
530 default hash or the hash specified with --hash. The hash result will be
531 truncated to the key size of the used cipher, or the size specified
532 with -s.
533
534 From stdin: Reading will continue until a newline (or until the maximum
535 input size is reached), with the trailing newline stripped. The maximum
536 input size is defined by the same compiled-in default as for the
537 maximum key file size and can be overwritten using --keyfile-size
538 option.
539
540 The data read will be hashed with the default hash or the hash
541 specified with --hash. The hash result will be truncated to the key
542 size of the used cipher, or the size specified with -s.
543
544 Note that if --key-file=- is used for reading the key from stdin,
545 trailing newlines are not stripped from the input.
546
547 If "plain" is used as argument to --hash, the input data will not be
548 hashed. Instead, it will be zero padded (if shorter than the key size)
549 or truncated (if longer than the key size) and used directly as the
550 binary key. This is useful for directly specifying a binary key. No
551 warning will be given if the amount of data read from stdin is less
552 than the key size.
553
554 From a key file: It will be truncated to the key size of the used
555 cipher or the size given by -s and directly used as a binary key.
556
557 WARNING: The --hash argument is being ignored. The --hash option is
558 usable only for stdin input in plain mode.
559
560 If the key file is shorter than the key, cryptsetup will quit with an
561 error. The maximum input size is defined by the same compiled-in
562 default as for the maximum key file size and can be overwritten using
563 --keyfile-size option.
564
565 Passphrase processing for LUKS
566 LUKS uses PBKDF to protect against dictionary attacks and to give some
567 protection to low-entropy passphrases (see cryptsetup FAQ).
568
569 From a terminal: The passphrase is read until the first newline and
570 then processed by PBKDF2 without the newline character.
571
572 From stdin: LUKS will read passphrases from stdin up to the first
573 newline character or the compiled-in maximum key file length. If
574 --keyfile-size is given, it is ignored.
575
576 From key file: The complete keyfile is read up to the compiled-in
577 maximum size. Newline characters do not terminate the input. The
578 --keyfile-size option can be used to limit what is read.
579
580 Passphrase processing: Whenever a passphrase is added to a LUKS header
581 (luksAddKey, luksFormat), the user may specify how much the time the
582 passphrase processing should consume. The time is used to determine the
583 iteration count for PBKDF2 and higher times will offer better
584 protection for low-entropy passphrases, but open will take longer to
585 complete. For passphrases that have entropy higher than the used key
586 length, higher iteration times will not increase security.
587
588 The default setting of one or two seconds is sufficient for most
589 practical cases. The only exception is a low-entropy passphrase used on
590 a device with a slow CPU, as this will result in a low iteration count.
591 On a slow device, it may be advisable to increase the iteration time
592 using the --iter-time option in order to obtain a higher iteration
593 count. This does slow down all later luksOpen operations accordingly.
594
595 Incoherent behavior for invalid passphrases/keys
596 LUKS checks for a valid passphrase when an encrypted partition is
597 unlocked. The behavior of plain dm-crypt is different. It will always
598 decrypt with the passphrase given. If the given passphrase is wrong,
599 the device mapped by plain dm-crypt will essentially still contain
600 encrypted data and will be unreadable.
601
602 Supported ciphers, modes, hashes and key sizes
603 The available combinations of ciphers, modes, hashes and key sizes
604 depend on kernel support. See /proc/crypto for a list of available
605 options. You might need to load additional kernel crypto modules in
606 order to get more options.
607
608 For the --hash option, if the crypto backend is libgcrypt, then all
609 algorithms supported by the gcrypt library are available. For other
610 crypto backends, some algorithms may be missing.
611
612 Notes on passphrases
613 Mathematics can’t be bribed. Make sure you keep your passphrases safe.
614 There are a few nice tricks for constructing a fallback, when suddenly
615 out of the blue, your brain refuses to cooperate. These fallbacks need
616 LUKS, as it’s only possible with LUKS to have multiple passphrases.
617 Still, if your attacker model does not prevent it, storing your
618 passphrase in a sealed envelope somewhere may be a good idea as well.
619
620 Notes on Random Number Generators
621 Random Number Generators (RNG) used in cryptsetup are always the kernel
622 RNGs without any modifications or additions to data stream produced.
623
624 There are two types of randomness cryptsetup/LUKS needs. One type
625 (which always uses /dev/urandom) is used for salts, the AF splitter and
626 for wiping deleted keyslots.
627
628 The second type is used for the volume key. You can switch between
629 using /dev/random and /dev/urandom here, see --use-random and
630 --use-urandom options. Using /dev/random on a system without enough
631 entropy sources can cause luksFormat to block until the requested
632 amount of random data is gathered. In a low-entropy situation (embedded
633 system), this can take a very long time and potentially forever. At the
634 same time, using /dev/urandom in a low-entropy situation will produce
635 low-quality keys. This is a serious problem, but solving it is out of
636 scope for a mere man-page. See urandom(4) for more information.
637
638 Authenticated disk encryption (EXPERIMENTAL)
639 Since Linux kernel version 4.12 dm-crypt supports authenticated disk
640 encryption.
641
642 Normal disk encryption modes are length-preserving (plaintext sector is
643 of the same size as a ciphertext sector) and can provide only
644 confidentiality protection, but not cryptographically sound data
645 integrity protection.
646
647 Authenticated modes require additional space per-sector for
648 authentication tag and use Authenticated Encryption with Additional
649 Data (AEAD) algorithms.
650
651 If you configure LUKS2 device with data integrity protection, there
652 will be an underlying dm-integrity device, which provides additional
653 per-sector metadata space and also provide data journal protection to
654 ensure atomicity of data and metadata update. Because there must be
655 additional space for metadata and journal, the available space for the
656 device will be smaller than for length-preserving modes.
657
658 The dm-crypt device then resides on top of such a dm-integrity device.
659 All activation and deactivation of this device stack is performed by
660 cryptsetup, there is no difference in using luksOpen for integrity
661 protected devices. If you want to format LUKS2 device with data
662 integrity protection, use --integrity option.
663
664 Since dm-integrity doesn’t support discards (TRIM), dm-crypt device on
665 top of it inherits this, so integrity protection mode doesn’t support
666 discards either.
667
668 Some integrity modes requires two independent keys (key for encryption
669 and for authentication). Both these keys are stored in one LUKS
670 keyslot.
671
672 WARNING: All support for authenticated modes is experimental and there
673 are only some modes available for now. Note that there are a very few
674 authenticated encryption algorithms that are suitable for disk
675 encryption. You also cannot use CRC32 or any other non-cryptographic
676 checksums (other than the special integrity mode "none"). If for some
677 reason you want to have integrity control without using authentication
678 mode, then you should separately configure dm-integrity independently
679 of LUKS2.
680
681 Notes on loopback device use
682 Cryptsetup is usually used directly on a block device (disk partition
683 or LVM volume). However, if the device argument is a file, cryptsetup
684 tries to allocate a loopback device and map it into this file. This
685 mode requires Linux kernel 2.6.25 or more recent which supports the
686 loop autoclear flag (loop device is cleared on the last close
687 automatically). Of course, you can always map a file to a loop-device
688 manually. See the cryptsetup FAQ for an example.
689
690 When device mapping is active, you can see the loop backing file in the
691 status command output. Also see losetup(8).
692
693 LUKS2 header locking
694 The LUKS2 on-disk metadata is updated in several steps and to achieve
695 proper atomic update, there is a locking mechanism. For an image in
696 file, code uses flock(2) system call. For a block device, lock is
697 performed over a special file stored in a locking directory (by default
698 /run/cryptsetup). The locking directory should be created with the
699 proper security context by the distribution during the boot-up phase.
700 Only LUKS2 uses locks, other formats do not use this mechanism.
701
702 LUKS on-disk format specification
703 For LUKS on-disk metadata specification see LUKS1
704 <https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification> and
705 LUKS2 <https://gitlab.com/cryptsetup/LUKS2-docs>.
706
708 Cryptsetup is originally written by Jana Saout <jana@saout.de>.
709 The LUKS extensions and original man page were written by Clemens
710 Fruhwirth <clemens@endorphin.org>.
711 Man page extensions by Milan Broz <gmazyland@gmail.com>.
712 Man page rewrite and extension by Arno Wagner <arno@wagner.name>.
713
715 Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
716 in Issues project section
717 <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
718
719 Please attach output of the failed command with --debug option added.
720
722 Cryptsetup FAQ
723 <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
724
725 cryptsetup(8), integritysetup(8) and veritysetup(8)
726
728 Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
729
730
731
732cryptsetup 2.6.1 2023-02-10 CRYPTSETUP(8)