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.
52 \fBPreviously used partitions:\fR If a partition was previously used,
53 it is a very good idea to wipe filesystem signatures, data, etc. before
54 creating a LUKS or plain dm-crypt container on it.
55 For a quick removal of filesystem signatures, use "wipefs". Take care
56 though that this may not remove everything. In particular md (RAID)
57 signatures at the end of a device may survive. It also does not
58 remove data. For a full wipe, overwrite the whole partition before
59 container creation. If you do not know how to to that, the
60 cryptsetup FAQ describes several options.
63 The following are valid actions for all supported device types.
65 \fIopen\fR <name> <device> \-\-type <device_type>
67 Opens (creates a mapping) with <name> backed by device <device>.
69 Device type can be \fIplain\fR, \fIluks\fR (default), \fIloopaes\fR
72 For backward compatibility there are \fBopen\fR command aliases:
74 \fBcreate\fR: open \-\-type plain <device> <name>\fR switched arguments)
76 \fBplainOpen\fR: open \-\-type plain
78 \fBluksOpen\fR: open \-\-type luks
80 \fBloopaesOpen\fR: open \-\-type loopaes
82 \fBtcryptOpen\fR: open \-\-type tcrypt
84 \fB<options>\fR are type specific and are described below
85 for individual device types.
89 Removes the existing mapping <name> and wipes the key from kernel memory.
91 For backward compatibility there are \fBclose\fR command aliases:
92 \fBremove\fR, \fBplainClose\fR, \fBluksClose\fR, \fBloopaesClose\fR,
93 \fBtcryptClose\fR (all behaves exactly the same, device type is
94 determined automatically from active device).
98 Reports the status for the mapping <name>.
102 Resizes an active mapping <name>.
104 If \-\-size (in sectors) is not specified, the size of the
105 underlying block device is used. Note that this does not
106 change the raw device geometry, it just changes how many
107 sectors of the raw device are represented in the mapped device.
109 Plain dm-crypt encrypts the device sector-by-sector with a
110 single, non-salted hash of the passphrase. No checks
111 are performed, no metadata is used. There is no formatting operation.
112 When the raw device is mapped (created), the usual device operations
113 can be used on the mapped device, including filesystem creation.
114 Mapped devices usually reside in /dev/mapper/<name>.
116 The following are valid plain device type actions:
118 \fIopen\fR \-\-type plain <device> <name>
120 \fIcreate\fR <name> <device> (\fBOBSOLETE syntax\fR)
122 Creates a mapping with <name> backed by device <device>.
124 \fB<options>\fR can be [\-\-hash, \-\-cipher, \-\-verify-passphrase,
125 \-\-key-file, \-\-keyfile-offset, \-\-key-size, \-\-offset, \-\-skip, \-\-size,
126 \-\-readonly, \-\-shared, \-\-allow-discards]
128 Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the raw
129 encrypted device /dev/sda10 to the mapped (decrypted) device
130 /dev/mapper/e1, which can then be mounted, fsck-ed or have a
131 filesystem created on it.
133 LUKS, the Linux Unified Key Setup, is a standard for disk encryption.
134 It adds a standardized header at the start of the device,
135 a key-slot area directly behind the header and the bulk
136 data area behind that. The whole set is called a 'LUKS container'.
137 The device that a LUKS container resides on is called a 'LUKS device'.
138 For most purposes both terms can be used interchangeably. But
139 note that when the LUKS header is at a nonzero offset
140 in a device, then the device is not a LUKS device anymore, but
141 has a LUKS container stored in it at an offset.
143 LUKS can manage multiple passphrases that can be individually revoked
144 or changed and that can be securely scrubbed from persistent
145 media due to the use of anti-forensic stripes. Passphrases
146 are protected against brute-force and dictionary
147 attacks by PBKDF2, which implements hash iteration and salting
150 Each passphrase, also called a
152 in this document, is associated with one of 8 key-slots.
153 Key operations that do not specify a slot affect the first slot
154 that matches the supplied passphrase or the first empty slot if
155 a new passphrase is added.
157 The following are valid LUKS actions:
159 \fIluksFormat\fR <device> [<key file>]
161 Initializes a LUKS partition and sets the initial passphrase
163 either via prompting or via <key file>. Note that
164 if the second argument is present, then the passphrase
165 is taken from the file given there, without the need
166 to use the \-\-key-file option. Also note that for both forms
167 of reading the passphrase from file you can
168 give '-' as file name, which results in the passphrase being read
169 from stdin and the safety-question being skipped.
171 You can only call luksFormat on a LUKS device that is not mapped.
173 \fB<options>\fR can be [\-\-cipher, \-\-verify-passphrase, \-\-key-size,
174 \-\-key-slot, \-\-key-file (takes precedence over optional second argument),
175 \-\-keyfile-offset, \-\-keyfile-size, \-\-use-random | \-\-use-urandom,
176 \-\-uuid, \-\-master-key-file].
178 \fBWARNING:\fR Doing a luksFormat on an existing LUKS container will
179 make all data the old container permanently irretrievable, unless
180 you have a header backup.
182 \fIopen\fR \-\-type luks <device> <name>
184 \fIluksOpen\fR <device> <name> (\fBold syntax\fR)
186 Opens the LUKS device <device> and sets up a mapping <name> after
187 successful verification of the supplied passphrase.
188 If the passphrase is not supplied via \-\-key-file, the command
189 prompts for it interactively.
191 The <device> parameter can be also specified by LUKS UUID in the
192 format UUID=<uuid>, which uses the symlinks in /dev/disk/by-uuid.
194 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
195 \-\-keyfile-size, \-\-readonly, \-\-test-passphrase,
196 \-\-allow-discards, \-\-header, \-\-key-slot, \-\-master-key-file].
198 \fIluksSuspend\fR <name>
200 Suspends an active device (all IO operations will blocked
201 and accesses to the device will wait indefinitely)
202 and wipes the encryption
203 key from kernel memory. Needs kernel 2.6.19 or later.
205 After this operation you have to use \fIluksResume\fR to reinstate
206 the encryption key and unblock the device or \fIclose\fR to remove
209 \fBWARNING:\fR never suspend the device on which the cryptsetup binary resides.
211 \fB<options>\fR can be [\-\-header].
213 \fIluksResume\fR <name>
215 Resumes a suspended device and reinstates the encryption key.
216 Prompts interactively for a passphrase if \-\-key-file is not given.
218 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-size, \-\-header]
220 \fIluksAddKey\fR <device> [<key file with new key>]
222 adds a new passphrase. An existing passphrase must be supplied
223 interactively or via \-\-key-file.
224 The new passphrase to be added can be specified interactively
225 or read from the file given as positional argument.
227 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
228 \-\-keyfile-size, \-\-new-keyfile-offset,
229 \-\-new-keyfile-size, \-\-key-slot, \-\-master-key-file].
231 \fIluksRemoveKey\fR <device> [<key file with passphrase to be removed>]
233 Removes the supplied passphrase from the LUKS device. The
234 passphrase to be removed can be specified interactively,
235 as positional argument or via \-\-key-file.
237 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
240 \fBWARNING:\fR If you read the passphrase from stdin
241 (without further argument or with '-' as argument
242 to \-\-key-file), batch-mode (-q) will be implicitely
243 switched on and no warning will be given when you remove the
244 last remaining passphrase from a LUKS container. Removing
245 the last passphrase makes the LUKS container permanently
248 \fIluksChangeKey\fR <device> [<new key file>]
250 Changes an existing passphrase. The passphrase
251 to be changed must be supplied interactively or via \-\-key-file.
252 The new passphrase can be supplied interactively or in
253 a file given as positional argument.
255 If a key-slot is specified (via \-\-key-slot), the passphrase
256 for that key-slot must be given and the new passphrase
257 will overwrite the specified key-slot. If no key-slot
258 is specified and there is still a free key-slot, then
259 the new passphrase will be put into a free key-slot before the
260 key-slot containing the old passphrase is purged. If there is
261 no free key-slot, then the key-slot with the old passphrase is
262 overwritten directly.
264 \fBWARNING:\fR If a key-slot is overwritten, a media failure
265 during this operation can cause the overwrite to fail after
266 the old passphrase has been wiped and make the LUKS container
269 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset,
270 \-\-keyfile-size, \-\-new-keyfile-offset,
271 \-\-new-keyfile-size, \-\-key-slot].
273 \fIluksKillSlot\fR <device> <key slot number>
275 Wipe the key-slot number <key slot> from the LUKS device. A remaining
276 passphrase must be supplied, either interactively or via \-\-key-file.
277 This command can remove the last remaining key-slot, but requires
278 an interactive confirmation when doing so. Removing the last
279 passphrase makes a LUKS container permanently inaccessible.
281 \fB<options>\fR can be [\-\-key-file, \-\-keyfile-offset, \-\-keyfile-size].
283 \fBWARNING:\fR If you read the passphrase from stdin
284 (without further argument or with '-' as argument
285 to \-\-key-file), batch-mode (-q) will be implicitely
286 switched on and no warning will be given when you remove the
287 last remaining passphrase from a LUKS container. Removing
288 the last passphrase makes the LUKS container permanently
291 \fIluksUUID\fR <device>
293 Print the UUID of a LUKS device.
295 Set new UUID if \fI\-\-uuid\fR option is specified.
297 \fIisLuks\fR <device>
299 Returns true, if <device> is a LUKS device, false otherwise.
300 Use option \-v to get human-readable feedback. 'Command successful.'
301 means the device is a LUKS device.
303 \fIluksDump\fR <device>
305 Dump the header information of a LUKS device.
307 If the \-\-dump-master-key option is used, the LUKS device master key is
308 dumped instead of the keyslot info. Beware that the master key cannot be
309 changed and can be used to decrypt the data stored in the LUKS container
310 without a passphrase and even without the LUKS header. This means
311 that if the master key is compromised, the whole device has to be
312 erased to prevent further access. Use this option carefully.
314 In order to dump the master key, a passphrase has to be supplied,
315 either interactively or via \-\-key-file.
317 \fB<options>\fR can be [\-\-dump-master-key, \-\-key-file,
318 \-\-keyfile-offset, \-\-keyfile-size].
320 \fBWARNING:\fR If \-\-dump-master-key is used with \-\-key-file
321 and the argument to \-\-key-file is '-', no validation question
322 will be asked and no warning given.
324 \fIluksHeaderBackup\fR <device> \-\-header-backup-file <file>
326 Stores a binary backup of the LUKS header and keyslot area.
328 Note: Using '-' as filename writes the header backup to a file named '-'.
330 \fBWARNING:\fR This backup file and a passphrase valid
331 at the time of backup allows decryption of the
332 LUKS data area, even if the passphrase was later changed or
333 removed from the LUKS device. Also note that with a header
334 backup you lose the ability to securely wipe the LUKS
335 device by just overwriting the header and key-slots. You
336 either need to securely erase all header backups in
337 addition or overwrite the encrypted data area as well.
338 The second option is less secure, as some sectors
339 can survive, e.g. due to defect management.
341 \fIluksHeaderRestore\fR <device> \-\-header-backup-file <file>
343 Restores a binary backup of the LUKS header and keyslot area
344 from the specified file.
346 Note: Using '-' as filename reads the header backup from a file named '-'.
348 \fBWARNING:\fR Header and keyslots will be replaced, only
349 the passphrases from the backup will work afterwards.
351 This command requires that the master key size and data offset
352 of the LUKS header already on the device and of the header backup
353 match. Alternatively, if there is no LUKS header on the device,
354 the backup will also be written to it.
355 .SH loop-AES EXTENSION
356 cryptsetup supports mapping loop-AES encrypted partition using
357 a compatibility mode.
359 \fIopen\fR \-\-type loopaes <device> <name> \-\-key-file <keyfile>
361 \fIloopaesOpen\fR <device> <name> \-\-key-file <keyfile> (\fBold syntax\fR)
363 Opens the loop-AES <device> and sets up a mapping <name>.
365 If the key file is encrypted with GnuPG, then you have to use
366 \-\-key-file=- and decrypt it before use, e.g. like this:
368 gpg \-\-decrypt <keyfile> | cryptsetup loopaesOpen \-\-key-file=- <device> <name>
370 Use \fB\-\-keyfile-size\fR to specify the proper key length if needed.
372 Use \fB\-\-offset\fR to specify device offset. Note that the units
373 need to be specified in number of 512 byte sectors.
375 Use \fB\-\-skip\fR to specify the IV offset. If the original device
376 used an offset and but did not use it in IV sector calculations,
377 you have to explicitly use \fB\-\-skip 0\fR in addition to the offset
380 Use \fB\-\-hash\fR to override the default hash function for
381 passphrase hashing (otherwise it is detected according to key
384 \fB<options>\fR can be [\-\-key-file, \-\-key-size, \-\-offset, \-\-skip,
385 \-\-hash, \-\-readonly, \-\-allow-discards].
387 See also section 7 of the FAQ and \fBhttp://loop-aes.sourceforge.net\fR
388 for more information regarding loop-AES.
389 .SH TCRYPT (TrueCrypt-compatible) EXTENSION
390 cryptsetup supports mapping of TrueCrypt or tcplay encrypted partition
391 using a native Linux kernel API.
392 Header formatting and TCRYPT header change is not supported, cryptsetup
393 never changes TCRYPT header on-device.
395 TCRYPT extension requires kernel userspace
396 crypto API to be available (introduced in Linux kernel 2.6.38).
397 If you are configuring kernel yourself, enable
398 "User-space interface for symmetric key cipher algorithms" in
399 "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option).
401 Because TCRYPT header is encrypted, you have to always provide valid
402 passphrase and keyfiles.
404 Cryptsetup should recognize all header variants, except legacy cipher chains
405 using LRW encryption mode with 64 bits encryption block (namely Blowfish
406 in LRW mode is not recognized, this is limitation of kernel crypto API).
408 \fBNOTE:\fR Activation with \fBtcryptOpen\fR is supported only for cipher chains
409 using LRW or XTS encryption modes.
411 The \fBtcryptDump\fR command should work for all recognized TCRYPT devices
412 and doesn't require superuser privilege.
414 To map system device (device with boot loader where the whole encrypted
415 system resides) use \fB\-\-tcrypt-system\fR option. Use the whole
416 device not the system partition as the device parameter.
418 To use hidden header (and map hidden device, if available),
419 use \fB\-\-tcrypt-hidden\fR option.
421 \fBNote:\fR There is no protection for a hidden volume if
422 the outer volume is mounted. The reason is that if there
423 were any protection, it would require some metadata describing
424 what to protect in the outer volume and the hidden volume would
425 become detectable. This is not a cryptsetup limitation, it is
426 a limitation of how hidden volumes are implemented in TrueCrypt.
427 The way to deal with this is not to mount the outer volume after
428 a hidden volume has been created in it.
429 This, in turn, causes the problem that after a while all
430 time-stamps in the outer volume become old and it becomes obvious
431 that it is unused. This may cause suspicion in itself.
432 An alternative is to protect the area of the hidden volume
433 from write access using the Device Mapper, e.g. by mapping it
434 to the zero or error target. This corresponds to the protection
435 mechanism present in TrueCrypt, but can cause filesystem
436 annomalies and error messages in the system logs that reveal
437 the presence of the hidden volume. For that reason, TrueCrypt
438 sets both outer and hidden volume to read-only once a write
439 that would have damaged the hidden volume is intercepted.
440 They claim this preserves plausible deniability, but that
441 claim seems doubtful, because it also limits possible
442 changes to the outer volume and may result in truncated
446 \fIopen\fR \-\-type tcrypt <device> <name>
448 \fItcryptOpen\fR <device> <name> (\fBold syntax\fR)
450 Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a mapping <name>.
452 \fB<options>\fR can be [\-\-key-file, \-\-tcrypt-hidden, \-\-tcrypt-system,
453 \-\-readonly, \-\-test-passphrase].
455 The keyfile parameter allows combination of file content with the
456 passphrase and can be repeated. Note that using keyfiles is compatible
457 with TCRYPT and is different from LUKS keyfile logic.
459 \fItcryptDump\fR <device>
461 Dump the header information of a TCRYPT device.
463 If the \-\-dump-master-key option is used, the TCRYPT device master key is
464 dumped instead of TCRYPT header info. Beware that the master key
465 (or concatenated master keys if cipher chain is used)
466 can be used to decrypt the data stored in the TCRYPT container without
468 This means that if the master key is compromised, the whole device has
469 to be erased to prevent further access. Use this option carefully.
471 \fB<options>\fR can be [\-\-dump-master-key, \-\-key-file, \-\-tcrypt-hidden,
474 The keyfile parameter allows combination of file content with the
475 passphrase and can be repeated.
477 See also \fBhttp://www.truecrypt.org\fR for more information regarding
480 Please note that cryptsetup does not use TrueCrypt code, please report
481 all problems related to this compatibility extension to cryptsetup project.
484 \fIrepair\fR <device>
486 Tries to repair the device metadata if possible. Currently supported only
487 for LUKS device type.
489 This command is useful to fix some known benign LUKS metadata
490 header corruptions. Only basic corruptions of unused keyslot
491 are fixable. This command will only change the LUKS header, not
494 \fBWARNING:\fR Always create a binary backup of the original
495 header before calling this command.
497 \fIbenchmark\fR <options>
499 Benchmarks ciphers and KDF (key derivation function).
500 Without parameters it tries to measure few common configurations.
502 To benchmark other ciphers or modes, you need to specify \fB\-\-cipher\fR
503 and \fB\-\-key-size\fR options or \fB\-\-hash\fR for KDF test.
505 \fBNOTE:\fR This benchmark is using memory only and is only informative.
506 You cannot directly predict real storage encryption speed from it.
508 For testing block ciphers, this benchmark requires kernel userspace
509 crypto API to be available (introduced in Linux kernel 2.6.38).
510 If you are configuring kernel yourself, enable
511 "User-space interface for symmetric key cipher algorithms" in
512 "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option).
514 \fB<options>\fR can be [\-\-cipher, \-\-key-size, \-\-hash].
517 .B "\-\-verbose, \-v"
518 Print more information on command execution.
521 Run in debug mode with full diagnostic logs. Debug output
522 lines are always prefixed by '#'.
524 .B "\-\-hash, \-h \fI<hash-spec>\fR"
525 Specifies the passphrase hash for \fIopen\fR (for plain and loopaes device types).
527 Specifies the hash used in the LUKS key setup scheme and volume key digest
528 for \fIluksFormat\fR.
530 The specified hash name is passed to the compiled-in crypto backend.
531 Different backends may support different hashes.
532 For \fIluksFormat\fR, the hash
533 algorithm must provide at least 160 bits of output, which
534 excludes, e.g., MD5. Do not use a non-crypto hash like
535 \fB"crc32"\fR as this breaks security.
537 Values compatible with old version of cryptsetup are
538 \fB"ripemd160"\fR for \fIopen \-\-type plain\fR and
539 \fB"sha1"\fR for \fIluksFormat\fR.
541 Use \fIcryptsetup \-\-help\fR to show the defaults.
543 .B "\-\-cipher, \-c \fI<cipher-spec>\fR"
544 Set the cipher specification string.
546 \fIcryptsetup \-\-help\fR shows the compiled-in defaults.
547 The current default in the distributed sources is
548 "aes-cbc-essiv:sha256" for plain dm-crypt and
549 "aes-xts-plain64" for LUKS.
551 For XTS mode you can optionally set a key size of
552 512 bits with the \-s option. Key size for XTS
553 mode is twice that for other modes for the same
556 XTS mode requires kernel 2.6.24 or later and plain64 requires
557 kernel 2.6.33 or later. More information can be found in the FAQ.
559 .B "\-\-verify-passphrase, \-y"
560 When interactively asking for a passphrase, ask for it twice
561 and complain if both inputs do not match. Advised when creating
562 a regular mapping for the first time, or when running
563 \fIluksFormat\fR. Ignores on input from file or stdin.
565 .B "\-\-key-file, \-d \fIname\fR"
566 Read the passphrase from file.
568 If the name given is "-", then the passphrase will be read from stdin.
569 In this case, reading will not stop at newline characters.
571 With LUKS, passphrases supplied via \-\-key-file are always
572 the existing passphrases requested by a command, except in
573 the case of \fIluksFormat\fR where \-\-key-file is equivalent
574 to the positional key file argument.
576 If you want to set a new passphrase via key file, you have to
577 use a positional argument to \fIluksAddKey\fR.
579 See section \fBNOTES ON PASSPHRASE PROCESSING\fR for more information.
581 .B "\-\-keyfile-offset \fIvalue\fR"
582 Skip \fIvalue\fR bytes at the beginning of the key file.
583 Works with all commands that accepts key files.
585 .B "\-\-keyfile-size, \-l \fIvalue\fR"
586 Read a maximum of \fIvalue\fR bytes from the key file.
587 Default is to read the whole file up to the compiled-in
588 maximum that can be queried with \-\-help. Supplying more
589 data than the compiled-in maximum aborts the operation.
591 This option is useful
592 to cut trailing newlines, for example. If \-\-keyfile-offset
593 is also given, the size count starts after the offset.
594 Works with all commands that accepts key files.
596 .B "\-\-new-keyfile-offset \fIvalue\fR"
597 Skip \fIvalue\fR bytes at the start when
598 adding a new passphrase from key file with
601 .B "\-\-new-keyfile-size \fIvalue\fR"
602 Read a maximum of \fIvalue\fR bytes when adding
603 a new passphrase from key file with \fIluksAddKey\fR.
604 Default is to read the whole file up to the compiled-in
605 maximum length that can be queried with \-\-help.
606 Supplying more than the compiled in maximum aborts the
608 When \-\-new-keyfile-offset is also given, reading starts
611 .B "\-\-master-key-file"
612 Use a master key stored in a file.
614 For \fIluksFormat\fR this
615 allows creating a LUKS header with this specific
616 master key. If the master key was taken from an existing
617 LUKS header and all other parameters are the same,
618 then the new header decrypts the data encrypted with the
619 header the master key was taken from.
621 For \fIluksAddKey\fR this allows adding a new passphrase
622 without having to know an exiting one.
624 For \fIopen\fR this allows to open the LUKS device
625 without giving a passphrase.
627 .B "\-\-dump-master-key"
628 For \fIluksDump\fR this option includes the master key in the displayed
629 information. Use with care, as the master key can be used to
630 bypass the passphrases, see also option \-\-master-key-file.
635 For \fIluksFormat\fR these options define which kernel random number
636 generator will be used to create the master key (which is a
639 See \fBNOTES ON RANDOM NUMBER GENERATORS\fR for more
640 information. Use \fIcryptsetup \-\-help\fR
641 to show the compiled-in default random number generator.
643 \fBWARNING:\fR In a low-entropy situation (e.g. in an
644 embedded system), both selections are problematic.
645 Using /dev/urandom can lead to weak keys.
646 Using /dev/random can block a long time, potentially
647 forever, if not enough entropy can be harvested by
650 .B "\-\-key-slot, \-S <0-7>"
651 For LUKS operations that add key material, this options allows you
652 to specify which key slot is selected for the new key.
653 This option can be used for \fIluksFormat\fR,
654 and \fIluksAddKey\fR.
656 In addition, for \fIopen\fR, this option selects a
657 specific key-slot to compare the passphrase against.
658 If the given passphrase would only match a different key-slot,
661 .B "\-\-key-size, \-s <bits>"
662 Sets key size in bits. The argument has to be a multiple of
663 8. The possible key-sizes are limited by the cipher and
666 See /proc/crypto for more information. Note that key-size
667 in /proc/crypto is stated in bytes.
669 This option can be used for \fIopen \-\-type plain\fR or \fIluksFormat\fR.
670 All other LUKS actions will use the key-size specified in the LUKS header.
671 Use \fIcryptsetup \-\-help\fR to show the compiled-in defaults.
673 .B "\-\-size, \-b <number of 512 byte sectors>"
674 Force the size of the underlying device in sectors of 512 bytes.
675 This option is only relevant for the \fIopen\fR and \fIresize\fR
678 .B "\-\-offset, \-o <number of 512 byte sectors>"
679 Start offset in the backend device in 512-byte sectors.
680 This option is only relevant for the \fIopen\fR action with plain
681 or loopaes device types.
683 .B "\-\-skip, \-p <number of 512 byte sectors>"
684 How many sectors of the encrypted data to skip at the beginning.
685 This option is only relevant for the \fIopen\fR action with plain
686 or loopaes device types.
688 This is different from the \-\-offset options with respect to
689 the sector numbers used in IV calculation.
690 Using \-\-offset will shift the IV calculation by the same negative amount.
691 Hence, if \-\-offset \fIn\fR, sector \fIn\fR will get a sector
692 number of \fI0\fR for the IV calculation.
693 Using \-\-skip causes sector \fIn\fR to also be the first sector
694 of the mapped device, but with its number for IV generation is \fIn\fR.
696 .B "\-\-readonly, \-r"
697 set up a read-only mapping.
700 Creates an additional mapping for one common
701 ciphertext device. Arbitrary mappings are supported.
702 This option is only relevant for the
703 \fIopen \-\-type plain\fR action. Use \-\-offset, \-\-size and \-\-skip to
704 specify the mapped area.
706 .B "\-\-iter-time, \-i <number of milliseconds>"
707 The number of milliseconds to spend with PBKDF2 passphrase processing.
708 This option is only relevant for LUKS operations that set or change
709 passphrases, such as \fIluksFormat\fR or \fIluksAddKey\fR.
710 Specifying 0 as parameter selects the compiled-in default.
712 .B "\-\-batch-mode, \-q"
713 Suppresses all confirmation questions. Use with care!
715 If the \-y option is not specified, this option also switches off
716 the passphrase verification for \fIluksFormat\fR.
718 .B "\-\-timeout, \-t <number of seconds>"
719 The number of seconds to wait before timeout on passphrase input
720 via terminal. It is relevant every time a passphrase is asked,
721 for example for \fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR.
722 It has no effect if used in conjunction with \-\-key-file.
724 This option is useful when the system
725 should not stall if the user does not input a passphrase,
726 e.g. during boot. The default is a value of 0 seconds,
727 which means to wait forever.
730 How often the input of the passphrase shall be retried.
731 This option is relevant
732 every time a passphrase is asked, for example for
733 \fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR.
734 The default is 3 tries.
736 .B "\-\-align-payload <number of 512 byte sectors>"
737 Align payload at a boundary of \fIvalue\fR 512-byte sectors.
738 This option is relevant for \fIluksFormat\fR.
740 If not specified, cryptsetup tries to use the topology info
741 provided by kernel for the underlying device to get optimal alignment.
742 If not available (or the calculated value is a multiple of the default)
743 data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte sectors).
745 For a detached LUKS header this option specifies the offset on the
746 data device. See also the \-\-header option.
748 .B "\-\-uuid=\fIUUID\fR"
749 Use the provided \fIUUID\fR for the \fIluksFormat\fR command
750 instead of generating new one. Changes the existing UUID when
751 used with the \fIluksUUID\fR command.
753 The UUID must be provided in the standard UUID format,
754 e.g. 12345678-1234-1234-1234-123456789abc.
756 .B "\-\-allow-discards\fR"
757 Allow the use of discard (TRIM) requests for device.
758 This option is only relevant for \fIopen\fR action.
760 \fBWARNING:\fR This command can have a negative security impact
761 because it can make filesystem-level operations visible on
762 the physical device. For example, information leaking
763 filesystem type, used space, etc. may be extractable from
764 the physical device if the discarded blocks can be located
765 later. If in doubt, do no use it.
767 A kernel version of 3.1 or later is needed. For earlier kernels
768 this option is ignored.
770 .B "\-\-test-passphrase\fR"
771 Do not activate device, just verify passphrase.
772 This option is only relevant for \fIopen\fR action (the device
773 mapping name is not mandatory if this option is used).
775 .B "\-\-header\fR <device or file storing the LUKS header>"
776 Use a detached (separated) metadata device or file where the
777 LUKS header is stored. This options allows to store ciphertext
778 and LUKS header on different devices.
780 This option is only relevant for LUKS devices and can be
781 used with the \fIluksFormat\fR, \fIopen\fR, \fIluksSuspend\fR,
782 \fIluksResume\fR, \fIstatus\fR and \fIresize\fR commands.
784 For \fIluksFormat\fR with a file name as argument to \-\-header,
785 it has to exist and be large enough to contain the LUKS header.
786 See the cryptsetup FAQ for header size calculation.
788 For other commands that change the LUKS header (e.g. \fIluksAddKey\fR),
789 specify the device or file with the LUKS header directly as the
792 If used with \fIluksFormat\fR, the \-\-align-payload option is taken
793 as absolute sector alignment on ciphertext device and can be zero.
795 \fBWARNING:\fR There is no check whether the ciphertext device specified
796 actually belongs to the header given. In fact you can specify an
797 arbitrary device as the ciphertext device for \fIopen\fR
798 with the \-\-header option. Use with care.
800 .B "\-\-force-password\fR"
801 Do not use password quality checking for new LUKS passwords.
803 This option applies only to \fIluksFormat\fR, \fIluksAddKey\fR and
804 \fIluksChangeKey\fR and is ignored if cryptsetup is built without
805 password quality checking support.
807 For more info about password quality check, see manual page
808 for \fBpwquality.conf(5)\fR.
811 Show the program version.
814 Show short option help.
817 Show help text and default parameters.
819 Cryptsetup returns 0 on success and a non-zero value on error.
821 Error codes are: 1 wrong parameters, 2 no permission (bad passphrase),
822 3 out of memory, 4 wrong device specified, 5 device already exists
824 .SH NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE
825 Note that no iterated hashing or salting is done in plain mode.
826 If hashing is done, it is a single direct hash. This means that
827 low-entropy passphrases are easy to attack in plain mode.
829 \fBFrom a terminal\fR: The passphrase is read until the
830 first newline, i.e. '\\n'.
831 The input without the newline character is processed with
832 the default hash or the hash specified with \-\-hash.
833 The has result will be truncated to the key size
834 of the used cipher, or the size specified with \-s.
836 \fBFrom stdin\fR: Reading will continue until a newline (or until
837 the maximum input size is reached), with the trailing newline
838 stripped. The maximum input size is defined by the same
839 compiled-in default as for the maximum key file size and can
840 be overwritten using \-\-keyfile-size option.
842 The data read will be hashed with the default hash
843 or the hash specified with \-\-hash.
844 The has result will be truncated to the key size
845 of the used cipher, or the size specified with \-s.
847 Note that if \-\-key-file=- is used for reading the key
848 from stdin, trailing newlines are not stripped from the input.
850 If "plain" is used as argument to \-\-hash, the input
851 data will not be hashed. Instead, it will be zero padded (if
852 shorter than the key size) or truncated (if longer than the
853 key size) and used directly as the binary key. This is useful for
854 directly specifying a binary key.
855 No warning will be given if the amount of data read from stdin is
856 less than the key size.
858 \fBFrom a key file\fR: It will be truncated to the
859 key size of the used cipher or the size given by \-s
860 and directly used as binary key.
861 if the key file is shorter than the key, cryptsetup
862 will quit with an error.
864 .SH NOTES ON PASSPHRASE PROCESSING FOR LUKS
865 LUKS uses PBKDF2 to protect against dictionary attacks
866 and to give some protection to low-entropy passphrases
867 (see RFC 2898 and the cryptsetup FAQ).
869 \fBFrom a terminal\fR: The passphrase is read until the
870 first newline and then processed by PBKDF2 without
871 the newline character.
874 LUKS will read passphrases from stdin up to the
875 first newline character or the compiled-in
876 maximum key file length. If \-\-keyfile-size is
877 given, it is ignored.
880 The complete keyfile is read up to the compiled-in
881 maximum size. Newline characters do not terminate the
882 input. The \-\-keyfile-size option can be used to limit
885 \fBPassphrase processing\fR:
886 Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat),
887 the user may specify how much the time the passphrase processing
888 should consume. The time is used to determine the iteration count
889 for PBKDF2 and higher times will offer better protection for
890 low-entropy passphrases, but open will take longer to
891 complete. For passphrases that have entropy higher than the
892 used key length, higher iteration times will not increase security.
894 The default setting of one second is sufficient for most
895 practical cases. The only exception is a low-entropy
896 passphrase used on a slow device.
897 .SH INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS
898 LUKS checks for a valid passphrase when an encrypted partition
899 is unlocked. The behavior of plain dm-crypt is different.
900 It will always decrypt with the passphrase given. If the
901 given passphrase is wrong, the device mapped by plain
902 dm-crypt will essentially still contain encrypted data and
904 .SH NOTES ON SUPPORTED CIPHERS, MODES, HASHES AND KEY SIZES
905 The available combinations of ciphers, modes, hashes and key sizes
906 depend on kernel support. See /proc/crypto for a list of available
907 options. You might need to load additional kernel crypto modules
908 in order to get more options.
910 For the \-\-hash option, if the crypto backend is libgcrypt,
911 then all algorithms supported by the gcrypt library are available.
912 For other crypto backends some algorithms may be missing.
913 .SH NOTES ON PASSPHRASES
914 Mathematics can't be bribed. Make sure you keep your passphrases safe.
915 There are a few nice tricks for constructing a fallback, when suddenly
916 out of the blue, your brain refuses to cooperate.
917 These fallbacks need LUKS, as it's only possible with LUKS
918 to have multiple passphrases. Still, if your attacker model does
919 not prevent it, storing your passphrase in a sealed envelope somewhere
920 may be a good idea as well.
921 .SH NOTES ON RANDOM NUMBER GENERATORS
922 Random Number Generators (RNG) used in cryptsetup are always the
923 kernel RNGs without any modifications or additions to data stream
926 There are two types of randomness cryptsetup/LUKS needs. One type
927 (which always uses /dev/urandom) is used for salts, the AF splitter
928 and for wiping deleted keyslots.
930 The second type is used for the volume (master) key. You can switch
931 between using /dev/random and /dev/urandom here, see
932 \fP\-\-use-random\fR and \fP\-\-use-urandom\fR
933 options. Using /dev/random on a system without enough entropy sources
934 can cause \fPluksFormat\fR to block until the requested amount of
935 random data is gathered. In a low-entropy situation (embedded system),
936 this can take a very long time and potentially forever. At the same
937 time, using /dev/urandom in a low-entropy situation will
938 produce low-quality keys. This is a serious problem, but solving
939 it is out of scope for a mere man-page.
940 See \fPurandom(4)\fR for more information.
941 .SH NOTES ON LOOPBACK DEVICE USE
942 Cryptsetup is usually used directly on a block device (disk
943 partition or LVM volume). However, if the device argument is a
944 file, cryptsetup tries to allocate a loopback device
945 and map it into this file. This mode requires Linux kernel 2.6.25
946 or more recent which supports the loop autoclear flag (loop device is
947 cleared on last close automatically). Of course, you can
948 always map a file to a loop-device manually. See the
949 cryptsetup FAQ for an example.
951 When device mapping is active, you can see the loop backing file in
952 the status command output. Also see losetup(8).
953 .SH DEPRECATED ACTIONS
955 The \fIreload\fR action is no longer supported.
956 Please use \fIdmsetup(8)\fR if you need to
957 directly manipulate with the device mapping table.
959 The \fIluksDelKey\fR was replaced with \fIluksKillSlot\fR.
962 Report bugs, including ones in the documentation, on
963 the cryptsetup mailing list at <dm-crypt@saout.de>
964 or in the 'Issues' section on LUKS website.
965 Please attach the output of the failed command with the
966 \-\-debug option added.
968 cryptsetup originally written by Christophe Saout <christophe@saout.de>
970 The LUKS extensions and original man page were written by
971 Clemens Fruhwirth <clemens@endorphin.org>.
973 Man page extensions by Milan Broz <gmazyland@gmail.com>.
975 Man page rewrite and extension by Arno Wagner <arno@wagner.name>.
977 Copyright \(co 2004 Christophe Saout
979 Copyright \(co 2004-2006 Clemens Fruhwirth
981 Copyright \(co 2009-2012 Red Hat, Inc.
983 Copyright \(co 2009-2012 Milan Broz
985 Copyright \(co 2012 Arno Wagner
987 This is free software; see the source for copying conditions. There is NO
988 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
990 The LUKS website at \fBhttp://code.google.com/p/cryptsetup/\fR
992 The cryptsetup FAQ, contained in the distribution package and
994 \fBhttp://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions\fR
996 The cryptsetup mailing list and list archive, see FAQ entry 1.6.
998 The LUKS on-disk format specification available at
999 \fBhttp://code.google.com/p/cryptsetup/wiki/Specification\fR