1 .TH CRYPTSETUP "8" "May 2012" "cryptsetup" "Maintenance Commands"
3 cryptsetup - manage plain dm-crypt and LUKS encrypted volumes
5 .B cryptsetup <options> <action> <action args>
8 cryptsetup is used to conveniently setup dm-crypt managed
9 device-mapper mappings. These include plain dm-crypt volumes and
10 LUKS volumes. The difference is that LUKS uses a metadata header
11 and can hence offer more features than plain dm-crypt. On the other
12 hand, the header is visible and vulnerable to damage.
13 .SH PLAIN DM-CRYPT OR LUKS?
15 Unless you understand the cryptographic background well, use LUKS.
16 With plain dm-crypt there are a number of possible user errors
17 that massively decrease security. While LUKS cannot fix them
18 all, it can lessen the impact for many of them.
21 A lot of good information on the risks of using encrypted storage,
22 on handling problems and on security aspects can be found in the
23 \fICryptsetup FAQ\fR. Read it. Nonetheless, some risks deserve
26 \fBBackup:\fR Storage media die. Encryption has no influence on that.
27 Backup is mandatory for encrypted data as well, if the data has any
28 worth. See the Cryptsetup FAQ for advice on how to do backup of an
31 \fBCharacter encoding:\fR If you enter a
32 passphrase with special symbols, the passphrase can change
33 depending character encoding. Keyboard settings can also change,
34 which can make blind input hard or impossible. For
35 example, switching from some ASCII 8-bit variant to UTF-8
36 can lead to a different binary encoding and hence different
37 passphrase seen by cryptsetup, even if what you see on
38 the terminal is exactly the same. It is therefore highly
39 recommended to select passphrase characters only from 7-bit
40 ASCII, as the encoding for 7-bit ASCII stays the same for
41 all ASCII variants and UTF-8.
43 \fBLUKS header:\fR If the header of a LUKS volume gets damaged,
44 all data is permanently lost unless you have a header-backup.
45 If a key-slot is damaged, it can only be restored from a header-backup
46 or if another active key-slot with known passphrase is undamaged.
47 Damaging the LUKS header is something people manage to do with
48 surprising frequency. This risk is the result of a trade-off
49 between security and safety, as LUKS is designed for fast and
50 secure wiping by just overwriting header and key-slot area.
53 Plain dm-crypt encrypts the device sector-by-sector with a
54 single, non-salted hash of the passphrase. No checks
55 are performed, no metadata is used. There is no formatting operation.
56 When the raw device is mapped (created), the usual device operations
57 can be used on the mapped device, including filesystem creation.
58 Mapped devices usually reside in /dev/mapper/<name>.
60 There are four operations:
62 \fIcreate\fR <name> <device>
64 Creates a mapping with <name> backed by device <device>.
66 \fB<options>\fR can be [\-\-hash, \-\-cipher, \-\-verify-passphrase,
67 \-\-key-file, \-\-keyfile-offset, \-\-key-size, \-\-offset, \-\-skip, \-\-size,
68 \-\-readonly, \-\-shared, \-\-allow-discards]
70 Example: 'cryptsetup create e1 /dev/sda10' maps the raw
71 encrypted device /dev/sda10 to the mapped (decrypted) device
72 /dev/mapper/e1, which can then be mounted, fsck-ed or have a
73 filesystem created on it.
77 Removes the existing mapping <name> and wipes the key from kernel memory.
81 Reports the status for the mapping <name>.
85 Resizes an active mapping <name>.
87 If \-\-size (in sectors) is not specified, the size of the
88 underlying block device is used. Note that this does not
89 change the raw device geometry, it just changes how many
90 sectors of the raw device are represented in the mapped device.
92 LUKS, the Linux Unified Key Setup, is a standard for disk encryption.
93 It adds a standardized header at the start of the device,
94 a key-slot area directly behind the header and the bulk
95 data area behind that. The whole set is called a 'LUKS container'.
96 The device that a LUKS container resides on is called a 'LUKS device'.
97 For most purposes both terms can be used interchangeably. But
98 note that when the LUKS header is at a nonzero offset
99 in a device, then the device is not a LUKS device anymore, but
100 has a LUKS container stored in it at an offset.
102 LUKS can manage multiple passphrases that can be individually revoked
103 or changed and that can be securely scrubbed from persistent
104 media due to the use of anti-forensic stripes. Passphrases
105 are protected against brute-force and dictionary
106 attacks by PBKDF2, which implements hash iteration and salting
109 Each passphrase, also called a
111 in this document, is associated with one of 8 key-slots.
112 Key operations that do not specify a slot affect the first slot
113 that matches the supplied passphrase or the first empty slot if
114 a new passphrase is added.
116 The following are valid LUKS actions:
118 \fIluksFormat\fR <device> [<key file>]
120 Initializes a LUKS partition and sets the initial passphrase
122 either via prompting or via <key file>. Note that
123 if the second argument is present, then the passphrase
124 is taken from the file given there, without the need
125 to use the \-\-key-file option. Also note that for both forms
126 of reading the passphrase from file you can
127 give '-' as file name, which results in the passphrase being read
128 from stdin and the safety-question being skipped.
130 You can only call luksFormat on a LUKS device that is not mapped.
132 \fB<options>\fR can be [\-\-cipher, \-\-verify-passphrase, \-\-key-size,
133 \-\-key-slot, \-\-key-file (takes precedence over optional second argument),
134 \-\-keyfile-offset, \-\-keyfile-size, \-\-use-random | \-\-use-urandom,
136 \-\-master-key-file].
138 \fBWARNING:\fR Doing a luksFormat on an existing LUKS container will
139 make all data the old container permanently irretrievable, unless
140 you have a header backup.
142 \fIluksOpen\fR <device> <name>
144 Opens the LUKS device <device> and sets up a mapping <name> after
145 successful verification of the supplied passphrase.
146 If the passphrase is not supplied via \-\-key-file, the command
147 prompts for it interactively.
149 The <device> parameter can be also specified by LUKS UUID in the
150 format UUID=<uuid>, which uses the symlinks in /dev/disk/by-uuid.
152 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
153 \-\-keyfile-size, \-\-readonly, \-\-test-passphrase,
154 \-\-allow-discards, \-\-header, \-\-key-slot, \-\-master-key-file].
156 \fIluksClose\fR <name>
158 identical to \fIremove\fR.
160 \fIluksSuspend\fR <name>
162 Suspends an active device (all IO operations will blocked
163 and accesses to the device will wait indefinitely)
164 and wipes the encryption
165 key from kernel memory. Needs kernel 2.6.19 or later.
167 After this operation you have to use \fIluksResume\fR to reinstate
168 the encryption key and unblock the device or \fIluksClose\fR to remove
171 \fBWARNING:\fR never suspend the device on which the cryptsetup binary resides.
173 \fB<options>\fR can be [\-\-header].
175 \fIluksResume\fR <name>
177 Resumes a suspended device and reinstates the encryption key.
178 Prompts interactively for a passphrase if \-\-key-file is not given.
180 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-size, \-\-header]
182 \fIluksAddKey\fR <device> [<key file with new key>]
184 adds a new passphrase. An existing passphrase must be supplied
185 interactively or via \-\-key-file.
186 The new passphrase to be added can be specified interactively
187 or read from the file given as positional argument.
189 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
190 \-\-keyfile-size, \-\-new-keyfile-offset,
191 \-\-new-keyfile-size, \-\-key-slot, \-\-master-key-file].
193 \fIluksRemoveKey\fR <device> [<key file with passphrase to be removed>]
195 Removes the supplied passphrase from the LUKS device. The
196 passphrase to be removed can be specified interactively,
197 as positional argument or via \-\-key-file.
199 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
202 \fBWARNING:\fR If you read the passphrase from stdin
203 (without further argument or with '-' as argument
204 to \-\-key-file), batch-mode (-q) will be implicitely
205 switched on and no warning will be given when you remove the
206 last remaining passphrase from a LUKS container. Removing
207 the last passphrase makes the LUKS container permanently
210 \fIluksChangeKey\fR <device> [<new key file>]
212 Changes an existing passphrase. The passphrase
213 to be changed must be supplied interactively or via \-\-key-file.
214 The new passphrase can be supplied interactively or in
215 a file given as positional argument.
217 If a key-slot is specified (via \-\-key-slot), the passphrase
218 for that key-slot must be given and the new passphrase
219 will overwrite the specified key-slot. If no key-slot
220 is specified and there is still a free key-slot, then
221 the new passphrase will be put into a free key-slot before the
222 key-slot containing the old passphrase is purged. If there is
223 no free key-slot, then the key-slot with the old passphrase is
224 overwritten directly.
226 \fBWARNING:\fR If a key-slot is overwritten, a media failure
227 during this operation can cause the overwrite to fail after
228 the old passphrase has been wiped and make the LUKS container
231 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
232 \-\-keyfile-size, \-\-new-keyfile-offset,
233 \-\-new-keyfile-size, \-\-key-slot].
235 \fIluksKillSlot\fR <device> <key slot number>
237 Wipe the key-slot number <key slot> from the LUKS device. A remaining
238 passphrase must be supplied, either interactively or via \-\-key-file.
239 This command can remove the last remaining key-slot, but requires
240 an interactive confirmation when doing so. Removing the last
241 passphrase makes a LUKS container permanently inaccessible.
243 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset, \-\-keyfile-size].
245 \fBWARNING:\fR If you read the passphrase from stdin
246 (without further argument or with '-' as argument
247 to \-\-key-file), batch-mode (-q) will be implicitely
248 switched on and no warning will be given when you remove the
249 last remaining passphrase from a LUKS container. Removing
250 the last passphrase makes the LUKS container permanently
253 \fIluksUUID\fR <device>
255 Print the UUID of a LUKS device.
257 Set new UUID if \fI\-\-uuid\fR option is specified.
259 \fIisLuks\fR <device>
261 Returns true, if <device> is a LUKS device, false otherwise.
262 Use option \-v to get human-readable feedback. 'Command successful.'
263 means the device is a LUKS device.
265 \fIluksDump\fR <device>
267 Dump the header information of a LUKS device.
269 If the \-\-dump-master-key option is used, the LUKS device master key is
270 dumped instead of the keyslot info. Beware that the master key cannot be
271 changed and can be used to decrypt the data stored in the LUKS container
272 without a passphrase and even without the LUKS header. This means
273 that if the master key is compromised, the whole device has to be
274 erased to prevent further access. Use this option carefully.
276 In order to dump the master key, a passphrase has to be supplied,
277 either interactively or via \-\-key-file.
279 \fB<options>\fR can be [\-\-dump-master-key, \-\-key-file,
280 \-\-keyfile-offset, \-\-keyfile-size].
282 \fBWARNING:\fR If \-\-dump-master-key is used with \-\-key-file
283 and the argument to \-\-key-file is '-', no validation question
284 will be asked and no warning given.
286 \fIluksHeaderBackup\fR <device> \-\-header-backup-file <file>
288 Stores a binary backup of the LUKS header and keyslot area.
290 Note: Using '-' as filename writes the header backup to a file named '-'.
292 \fBWARNING:\fR This backup file and a passphrase valid
293 at the time of backup allows decryption of the
294 LUKS data area, even if the passphrase was later changed or
295 removed from the LUKS device. Also note that with a header
296 backup you lose the ability to securely wipe the LUKS
297 device by just overwriting the header and key-slots. You
298 either need to securely erase all header backups in
299 addition or overwrite the encrypted data area as well.
300 The second option is less secure, as some sectors
301 can survive, e.g. due to defect management.
303 \fIluksHeaderRestore\fR <device> \-\-header-backup-file <file>
305 Restores a binary backup of the LUKS header and keyslot area
306 from the specified file.
308 Note: Using '-' as filename reads the header backup from a file named '-'.
310 \fBWARNING:\fR Header and keyslots will be replaced, only
311 the passphrases from the backup will work afterwards.
313 This command requires that the master key size and data offset
314 of the LUKS header already on the device and of the header backup
315 match. Alternatively, if there is no LUKS header on the device,
316 the backup will also be written to it.
318 \fIrepair\fR <device>
320 Tries to repair the LUKS device metadata if possible.
322 This command is useful to fix some known benign LUKS metadata
323 header corruptions. Only basic corruptions of unused keyslot
324 are fixable. This command will only change the LUKS header, not
327 \fBWARNING:\fR Always create a binary backup of the original
328 header before calling this command.
329 .SH loop-AES EXTENSION
330 cryptsetup supports mapping loop-AES encrypted partition using
331 a compatibility mode.
333 \fIloopaesOpen\fR <device> <name> \-\-key-file <keyfile>
335 Opens the loop-AES <device> and sets up a mapping <name>.
337 If the key file is encrypted with GnuPG, then you have to use
338 \-\-key-file=- and decrypt it before use, e.g. like this:
340 gpg \-\-decrypt <keyfile> | cryptsetup loopaesOpen \-\-key-file=- <device> <name>
342 Use \fB\-\-key-file-size\fR to specify the proper key length if needed.
344 Use \fB\-\-offset\fR to specify device offset. Note that the units
345 need to be specified in number of 512 byte sectors.
347 Use \fB\-\-skip\fR to specify the IV offset. If the original device
348 used an offset and but did not use it in IV sector calculations,
349 you have to explicitly use \fB\-\-skip 0\fR in addition to the offset
352 Use \fB\-\-hash\fR to override the default hash function for
353 passphrase hashing (otherwise it is detected according to key
356 \fB<options>\fR can be [\-\-key-file, \-\-key-size, \-\-offset, \-\-skip,
357 \-\-hash, \-\-readonly, \-\-allow-discards].
359 \fIloopaesClose\fR <name>
361 Identical to \fIremove\fR.
363 See also section 7 of the FAQ and \fBhttp://loop-aes.sourceforge.net\fR
364 for more information regarding loop-AES.
367 .B "\-\-verbose, \-v"
368 Print more information on command execution.
371 Run in debug mode with full diagnostic logs. Debug output
372 lines are always prefixed by '#'.
374 .B "\-\-hash, \-h \fI<hash-spec>\fR"
375 Specifies the passphrase hash for \fIcreate\fR and \fIloopaesOpen\fR.
377 Specifies the hash used in the LUKS key setup scheme and volume key digest
378 for \fIluksFormat\fR.
380 The specified hash name is passed to the compiled-in crypto backend.
381 Different backends may support different hashes.
382 For \fIluksFormat\fR, the hash
383 algorithm must provide at least 160 bits of output, which
384 excludes, e.g., MD5. Do not use a non-crypto hash like
385 \fB"crc32"\fR as this breaks security.
387 Values compatible with old version of cryptsetup are
388 \fB"ripemd160"\fR for \fIcreate\fR and
389 \fB"sha1"\fR for \fIluksFormat\fR.
391 Use \fIcryptsetup \-\-help\fR to show the defaults.
393 .B "\-\-cipher, \-c \fI<cipher-spec>\fR"
394 Set the cipher specification string.
396 \fIcryptsetup \-\-help\fR shows the compiled-in defaults.
397 The current default in the distributed sources is
398 "aes-cbc-essiv:sha256" for both plain dm-crypt and LUKS.
400 For XTS mode (a possible future default), use "aes-xts-plain"
401 or better "aes-xts-plain64"
402 as cipher specification and optionally set a key size of
403 512 bits with the \-s option. Key size for XTS
404 mode is twice that for other modes for the same
407 XTS mode requires kernel 2.6.24 or later and plain64 requires
408 kernel 2.6.33 or later. More information can be found in the FAQ.
410 .B "\-\-verify-passphrase, \-y"
411 When interactively asking for a passphrase, ask for it twice
412 and complain if both inputs do not match. Advised when creating
413 a regular mapping for the first time, or when running
414 \fIluksFormat\fR. Ignores on input from file or stdin.
416 .B "\-\-key-file, \-d \fIname\fR"
417 Read the passphrase from file.
419 If the name given is "-", then the passphrase will be read from stdin.
420 In this case, reading will not stop at newline characters.
422 With LUKS, passphrases supplied via \-\-key-file are always
423 the existing passphrases requested by a command, except in
424 the case of \fIluksFormat\fR where \-\-key-file is equivalent
425 to the positional key file argument.
427 If you want to set a new passphrase via key file, you have to
428 use a positional argument to \fIluksAddKey\fR.
430 See section \fBNOTES ON PASSPHRASE PROCESSING\fR for more information.
432 .B "\-\-keyfile-offset \fIvalue\fR"
433 Skip \fIvalue\fR bytes at the beginning of the key file.
434 Works with all commands that accepts key files.
436 .B "\-\-keyfile-size, \-l \fIvalue\fR"
437 Read a maximum of \fIvalue\fR bytes from the key file.
438 Default is to read the whole file up to the compiled-in
439 maximum that can be queried with \-\-help. Supplying more
440 data than the compiled-in maximum aborts the operation.
442 This option is useful
443 to cut trailing newlines, for example. If \-\-keyfile-offset
444 is also given, the size count starts after the offset.
445 Works with all commands that accepts key files.
447 .B "\-\-new-keyfile-offset \fIvalue\fR"
448 Skip \fIvalue\fR bytes at the start when
449 adding a new passphrase from key file with
452 .B "\-\-new-keyfile-size \fIvalue\fR"
453 Read a maximum of \fIvalue\fR bytes when adding
454 a new passphrase from key file with \fIluksAddKey\fR.
455 Default is to read the whole file up to the compiled-in
456 maximum length that can be queried with \-\-help.
457 Supplying more than the compiled in maximum aborts the
459 When \-\-new-keyfile-offset is also given, reading starts
462 .B "\-\-master-key-file"
463 Use a master key stored in a file.
465 For \fIluksFormat\fR this
466 allows creating a LUKS header with this specific
467 master key. If the master key was taken from an existing
468 LUKS header and all other parameters are the same,
469 then the new header decrypts the data encrypted with the
470 header the master key was taken from.
472 For \fIluksAddKey\fR this allows adding a new passphrase
473 without having to know an exiting one.
475 For \fIluksOpen\fR this allows to open the LUKS device
476 without giving a passphrase.
478 .B "\-\-dump-master-key"
479 For \fIluksDump\fR this option includes the master key in the displayed
480 information. Use with care, as the master key can be used to
481 bypass the passphrases, see also option \-\-master-key-file.
486 For \fIluksFormat\fR these options define which kernel random number
487 generator will be used to create the master key (which is a
490 See \fBNOTES ON RANDOM NUMBER GENERATORS\fR for more
491 information. Use \fIcryptsetup \-\-help\fR
492 to show the compiled-in default random number generator.
494 \fBWARNING:\fR In a low-entropy situation (e.g. in an
495 embedded system), both selections are problematic.
496 Using /dev/urandom can lead to weak keys.
497 Using /dev/random can block a long time, potentially
498 forever, if not enough entropy can be harvested by
501 .B "\-\-key-slot, \-S <0-7>"
502 For LUKS operations that add key material, this options allows you
503 to specify which key slot is selected for the new key.
504 This option can be used for \fIluksFormat\fR,
505 and \fIluksAddKey\fR.
507 In addition, for \fIluksOpen\fR, this option selects a
508 specific key-slot to compare the passphrase against.
509 If the given passphrase would only match a different key-slot,
512 .B "\-\-key-size, \-s <bits>"
513 Sets key size in bits. The argument has to be a multiple of
514 8. The possible key-sizes are limited by the cipher and
517 See /proc/crypto for more information. Note that key-size
518 in /proc/crypto is stated in bytes.
520 This option can be used for \fIcreate\fR or \fIluksFormat\fR. All
521 other LUKS actions will use the key-size specified in the LUKS header.
522 Use \fIcryptsetup \-\-help\fR to show the compiled-in defaults.
524 .B "\-\-size, \-b <number of 512 byte sectors>"
525 Force the size of the underlying device in sectors of 512 bytes.
526 This option is only relevant for the \fIcreate\fR and \fIresize\fR
529 .B "\-\-offset, \-o <number of 512 byte sectors>"
530 Start offset in the backend device in 512-byte sectors.
531 This option is only relevant for the \fIcreate\fR and \fIloopaesOpen\fR
534 .B "\-\-skip, \-p <number of 512 byte sectors>"
535 How many sectors of the encrypted data to skip at the beginning.
536 This option is only relevant for \fIcreate\fR and \fIloopaesOpen\fR action.
538 This is different from the \-\-offset options with respect to
539 the sector numbers used in IV calculation.
540 Using \-\-offset will shift the IV calculation by the same negative amount.
541 Hence, if \-\-offset \fIn\fR, sector \fIn\fR will get a sector
542 number of \fI0\fR for the IV calculation.
543 Using \-\-skip causes sector \fIn\fR to also be the first sector
544 of the mapped device, but with its number for IV generation is \fIn\fR.
546 .B "\-\-readonly, \-r"
547 set up a read-only mapping.
550 Creates an additional mapping for one common
551 ciphertext device. Arbitrary mappings are supported.
552 This option is only relevant for the
553 \fIcreate\fR action. Use \-\-offset, \-\-size and \-\-skip to
554 specify the mapped area.
556 .B "\-\-iter-time, \-i <number of milliseconds>"
557 The number of milliseconds to spend with PBKDF2 passphrase processing.
558 This option is only relevant for LUKS operations that set or change
559 passphrases, such as \fIluksFormat\fR or \fIluksAddKey\fR.
560 Specifying 0 as parameter selects the compiled-in default.
562 .B "\-\-batch-mode, \-q"
563 Suppresses all confirmation questions. Use with care!
565 If the \-y option is not specified, this option also switches off
566 the passphrase verification for \fIluksFormat\fR.
568 .B "\-\-timeout, \-t <number of seconds>"
569 The number of seconds to wait before timeout on passphrase input
570 via terminal. It is relevant every time a passphrase is asked,
571 for example for \fIcreate\fR, \fIluksOpen\fR, \fIluksFormat\fR
572 or \fIluksAddKey\fR. It has no effect if used in conjunction
575 This option is useful when the system
576 should not stall if the user does not input a passphrase,
577 e.g. during boot. The default is a value of 0 seconds,
578 which means to wait forever.
581 How often the input of the passphrase shall be retried.
582 This option is relevant
583 every time a passphrase is asked, for example for
584 \fIcreate\fR, \fIluksOpen\fR, \fIluksFormat\fR
585 or \fIluksAddKey\fR. The default is 3 tries.
587 .B "\-\-align-payload <number of 512 byte sectors>"
588 Align payload at a boundary of \fIvalue\fR 512-byte sectors.
589 This option is relevant for \fIluksFormat\fR.
591 If not specified, cryptsetup tries to use the topology info
592 provided by kernel for the underlying device to get optimal alignment.
593 If not available (or the calculated value is a multiple of the default)
594 data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte sectors).
596 For a detached LUKS header this option specifies the offset on the
597 data device. See also the \-\-header option.
599 .B "\-\-uuid=\fIUUID\fR"
600 Use the provided \fIUUID\fR for the \fIluksFormat\fR command
601 instead of generating new one. Changes the existing UUID when
602 used with the \fIluksUUID\fR command.
604 The UUID must be provided in the standard UUID format,
605 e.g. 12345678-1234-1234-1234-123456789abc.
607 .B "\-\-allow-discards\fR"
608 Allow the use of discard (TRIM) requests for device.
609 This option is only relevant for \fIcreate\fR, \fIluksOpen\fR
610 and \fIloopaesOpen\fR.
612 \fBWARNING:\fR This command can have a negative security impact
613 because it can make filesystem-level operations visible on
614 the physical device. For example, information leaking
615 filesystem type, used space, etc. may be extractable from
616 the physical device if the discarded blocks can be located
617 later. If in doubt, do no use it.
619 A kernel version of 3.1 or later is needed. For earlier kernels
620 this option is ignored.
622 .B "\-\-test-passphrase\fR"
623 Do not activate device, just verify passphrase.
624 This option is only relevant for \fIluksOpen\fR.
626 .B "\-\-header\fR <device or file storing the LUKS header>"
627 Use a detached (separated) metadata device or file where the
628 LUKS header is stored. This options allows to store ciphertext
629 and LUKS header on different devices.
631 This option is only relevant for LUKS devices and can be
632 used with the \fIluksFormat\fR, \fIluksOpen\fR, \fIluksSuspend\fR,
633 \fIluksResume\fR, \fIstatus\fR and \fIresize\fR commands.
635 For \fIluksFormat\fR with a file name as argument to \-\-header,
636 it has to exist and be large enough to contain the LUKS header.
637 See the cryptsetup FAQ for header size calculation.
639 For other commands that change the LUKS header (e.g. \fIluksAddKey\fR),
640 specify the device or file with the LUKS header directly as the
643 If used with \fIluksFormat\fR, the \-\-align-payload option is taken
644 as absolute sector alignment on ciphertext device and can be zero.
646 \fBWARNING:\fR There is no check whether the ciphertext device specified
647 actually belongs to the header given. In fact you can specify an
648 arbitrary device as the ciphertext device for \fIluksOpen\fR
649 with the \-\-header option. Use with care.
652 Show the program version.
654 Cryptsetup returns 0 on success and a non-zero value on error.
656 Error codes are: 1 wrong parameters, 2 no permission (bad passphrase),
657 3 out of memory, 4 wrong device specified, 5 device already exists
659 .SH NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE
660 Note that no iterated hashing or salting is done in plain mode.
661 If hashing is done, it is a single direct hash. This means that
662 low-entropy passphrases are easy to attack in plain mode.
664 \fBFrom a terminal\fR: The passphrase is read until the
665 first newline, i.e. '\\n'.
666 The input without the newline character is processed with
667 the default hash or the hash specified with \-\-hash.
668 The has result will be truncated to the key size
669 of the used cipher, or the size specified with \-s.
671 \fBFrom stdin\fR: Reading will continue until a newline (or until
672 the maximum input size is reached), with the trailing newline
673 stripped. The maximum input size is defined by the same
674 compiled-in default as for the maximum key file size and can
675 be overwritten using \-\-keyfile-size option.
677 The data read will be hashed with the default hash
678 or the hash specified with \-\-hash.
679 The has result will be truncated to the key size
680 of the used cipher, or the size specified with \-s.
682 Note that if \-\-key-file=- is used for reading the key
683 from stdin, trailing newlines are not stripped from the input.
685 If "plain" is used as argument to \-\-hash, the input
686 data will not be hashed. Instead, it will be zero padded (if
687 shorter than the key size) or truncated (if longer than the
688 key size) and used directly as the binary key. This is useful for
689 directly specifying a binary key.
690 No warning will be given if the amount of data read from stdin is
691 less than the key size.
693 \fBFrom a key file\fR: It will be truncated to the
694 key size of the used cipher or the size given by \-s
695 and directly used as binary key.
696 if the key file is shorter than the key, cryptsetup
697 will quit with an error.
699 .SH NOTES ON PASSPHRASE PROCESSING FOR LUKS
700 LUKS uses PBKDF2 to protect against dictionary attacks
701 and to give some protection to low-entropy passphrases
702 (see RFC 2898 and the cryptsetup FAQ).
704 \fBFrom a terminal\fR: The passphrase is read until the
705 first newline and then processed by PBKDF2 without
706 the newline character.
709 LUKS will read passphrases from stdin up to the
710 first newline character or the compiled-in
711 maximum key file length. If \-\-keyfile-size is
712 given, it is ignored.
715 The complete keyfile is read up to the compiled-in
716 maximum size. Newline characters do not terminate the
717 input. The \-\-keyfile-size option can be used to limit
720 \fBPassphrase processing\fR:
721 Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat),
722 the user may specify how much the time the passphrase processing
723 should consume. The time is used to determine the iteration count
724 for PBKDF2 and higher times will offer better protection for
725 low-entropy passphrases, but luksOpen will take longer to
726 complete. For passphrases that have entropy higher than the
727 used key length, higher iteration times will not increase security.
729 The default setting of one second is sufficient for most
730 practical cases. The only exception is a low-entropy
731 passphrase used on a slow device.
732 .SH INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS
733 LUKS checks for a valid passphrase when an encrypted partition
734 is unlocked. The behavior of plain dm-crypt is different.
735 It will always decrypt with the passphrase given. If the
736 given passphrase is wrong, the device mapped by plain
737 dm-crypt will essentially still contain encrypted data and
739 .SH NOTES ON SUPPORTED CIPHERS, MODES, HASHES AND KEY SIZES
740 The available combinations of ciphers, modes, hashes and key sizes
741 depend on kernel support. See /proc/crypto for a list of available
742 options. You might need to load additional kernel crypto modules
743 in order to get more options.
745 For the \-\-hash option, if the crypto backend is libgcrypt,
746 then all algorithms supported by the gcrypt library are available.
747 For other crypto backends some algorithms may be missing.
748 .SH NOTES ON PASSPHRASES
749 Mathematics can't be bribed. Make sure you keep your passphrases safe.
750 There are a few nice tricks for constructing a fallback, when suddenly
751 out of the blue, your brain refuses to cooperate.
752 These fallbacks need LUKS, as it's only possible with LUKS
753 to have multiple passphrases. Still, if your attacker model does
754 not prevent it, storing your passphrase in a sealed envelope somewhere
755 may be a good idea as well.
756 .SH NOTES ON RANDOM NUMBER GENERATORS
757 Random Number Generators (RNG) used in cryptsetup are always the
758 kernel RNGs without any modifications or additions to data stream
761 There are two types of randomness cryptsetup/LUKS needs. One type
762 (which always uses /dev/urandom) is used for salts, the AF splitter
763 and for wiping deleted keyslots.
765 The second type is used for the volume (master) key. You can switch
766 between using /dev/random and /dev/urandom here, see
767 \fP\-\-use-random\fR and \fP\-\-use-urandom\fR
768 options. Using /dev/random on a system without enough entropy sources
769 can cause \fPluksFormat\fR to block until the requested amount of
770 random data is gathered. In a low-entropy situation (embedded system),
771 this can take a very long time and potentially forever. At the same
772 time, using /dev/urandom in a low-entropy situation will
773 produce low-quality keys. This is a serious problem, but solving
774 it is out of scope for a mere man-page.
775 See \fPurandom(4)\fR for more information.
776 .SH NOTES ON LOOPBACK DEVICE USE
777 Cryptsetup is usually used directly on a block device (disk
778 partition or LVM volume). However, if the device argument is a
779 file, cryptsetup tries to allocate a loopback device
780 and map it into this file. This mode requires Linux kernel 2.6.25
781 or more recent which supports the loop autoclear flag (loop device is
782 cleared on last close automatically). Of course, you can
783 always map a file to a loop-device manually. See the
784 cryptsetup FAQ for an example.
786 When device mapping is active, you can see the loop backing file in
787 the status command output. Also see losetup(8).
788 .SH DEPRECATED ACTIONS
790 The \fIreload\fR action is no longer supported.
791 Please use \fIdmsetup(8)\fR if you need to
792 directly manipulate with the device mapping table.
794 The \fIluksDelKey\fR was replaced with \fIluksKillSlot\fR.
797 Report bugs, including ones in the documentation, on
798 the cryptsetup mailing list at <dm-crypt@saout.de>
799 or in the 'Issues' section on LUKS website.
800 Please attach the output of the failed command with the
801 \-\-debug option added.
803 cryptsetup originally written by Christophe Saout <christophe@saout.de>
805 The LUKS extensions and original man page were written by
806 Clemens Fruhwirth <clemens@endorphin.org>.
808 Man page extensions by Milan Broz <gmazyland@gmail.com>.
810 Man page rewrite and extension by Arno Wagner <arno@wagner.name>.
812 Copyright \(co 2004 Christophe Saout
814 Copyright \(co 2004-2006 Clemens Fruhwirth
816 Copyright \(co 2009-2012 Red Hat, Inc.
818 Copyright \(co 2012 Arno Wagner
820 This is free software; see the source for copying conditions. There is NO
821 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
823 The LUKS website at \fBhttp://code.google.com/p/cryptsetup/\fR
825 The cryptsetup FAQ, contained in the distribution package and
827 \fBhttp://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions\fR
829 The cryptsetup mailing list and list archive, see FAQ entry 1.6.
831 The LUKS on-disk format specification available at
832 \fBhttp://code.google.com/p/cryptsetup/wiki/Specification\fR