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 time-stamps
430 in the outer volume become old and it becomes obvious that
431 it is unused. This may cause suspicion in itself.
434 \fIopen\fR \-\-type tcrypt <device> <name>
436 \fItcryptOpen\fR <device> <name> (\fBold syntax\fR)
438 Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a mapping <name>.
440 \fB<options>\fR can be [\-\-key-file, \-\-tcrypt-hidden, \-\-tcrypt-system,
441 \-\-readonly, \-\-test-passphrase].
443 The keyfile parameter allows combination of file content with the
444 passphrase and can be repeated. Note that using keyfiles is compatible
445 with TCRYPT and is different from LUKS keyfile logic.
447 \fItcryptDump\fR <device>
449 Dump the header information of a TCRYPT device.
451 If the \-\-dump-master-key option is used, the TCRYPT device master key is
452 dumped instead of TCRYPT header info. Beware that the master key
453 (or concatenated master keys if cipher chain is used)
454 can be used to decrypt the data stored in the TCRYPT container without
456 This means that if the master key is compromised, the whole device has
457 to be erased to prevent further access. Use this option carefully.
459 \fB<options>\fR can be [\-\-dump-master-key, \-\-key-file, \-\-tcrypt-hidden,
462 The keyfile parameter allows combination of file content with the
463 passphrase and can be repeated.
465 See also \fBhttp://www.truecrypt.org\fR for more information regarding
468 Please note that cryptsetup does not use TrueCrypt code, please report
469 all problems related to this compatibility extension to cryptsetup project.
472 \fIrepair\fR <device>
474 Tries to repair the device metadata if possible. Currently supported only
475 for LUKS device type.
477 This command is useful to fix some known benign LUKS metadata
478 header corruptions. Only basic corruptions of unused keyslot
479 are fixable. This command will only change the LUKS header, not
482 \fBWARNING:\fR Always create a binary backup of the original
483 header before calling this command.
485 \fIbenchmark\fR <options>
487 Benchmarks ciphers and KDF (key derivation function).
488 Without parameters it tries to measure few common configurations.
490 To benchmark other ciphers or modes, you need to specify \fB\-\-cipher\fR
491 and \fB\-\-key-size\fR options or \fB\-\-hash\fR for KDF test.
493 \fBNOTE:\fR This benchmark is using memory only and is only informative.
494 You cannot directly predict real storage encryption speed from it.
496 For testing block ciphers, this benchmark requires kernel userspace
497 crypto API to be available (introduced in Linux kernel 2.6.38).
498 If you are configuring kernel yourself, enable
499 "User-space interface for symmetric key cipher algorithms" in
500 "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option).
502 \fB<options>\fR can be [\-\-cipher, \-\-key-size, \-\-hash].
505 .B "\-\-verbose, \-v"
506 Print more information on command execution.
509 Run in debug mode with full diagnostic logs. Debug output
510 lines are always prefixed by '#'.
512 .B "\-\-hash, \-h \fI<hash-spec>\fR"
513 Specifies the passphrase hash for \fIopen\fR (for plain and loopaes device types).
515 Specifies the hash used in the LUKS key setup scheme and volume key digest
516 for \fIluksFormat\fR.
518 The specified hash name is passed to the compiled-in crypto backend.
519 Different backends may support different hashes.
520 For \fIluksFormat\fR, the hash
521 algorithm must provide at least 160 bits of output, which
522 excludes, e.g., MD5. Do not use a non-crypto hash like
523 \fB"crc32"\fR as this breaks security.
525 Values compatible with old version of cryptsetup are
526 \fB"ripemd160"\fR for \fIopen \-\-type plain\fR and
527 \fB"sha1"\fR for \fIluksFormat\fR.
529 Use \fIcryptsetup \-\-help\fR to show the defaults.
531 .B "\-\-cipher, \-c \fI<cipher-spec>\fR"
532 Set the cipher specification string.
534 \fIcryptsetup \-\-help\fR shows the compiled-in defaults.
535 The current default in the distributed sources is
536 "aes-cbc-essiv:sha256" for plain dm-crypt and
537 "aes-xts-plain64" for LUKS.
539 For XTS mode you can optionally set a key size of
540 512 bits with the \-s option. Key size for XTS
541 mode is twice that for other modes for the same
544 XTS mode requires kernel 2.6.24 or later and plain64 requires
545 kernel 2.6.33 or later. More information can be found in the FAQ.
547 .B "\-\-verify-passphrase, \-y"
548 When interactively asking for a passphrase, ask for it twice
549 and complain if both inputs do not match. Advised when creating
550 a regular mapping for the first time, or when running
551 \fIluksFormat\fR. Ignores on input from file or stdin.
553 .B "\-\-key-file, \-d \fIname\fR"
554 Read the passphrase from file.
556 If the name given is "-", then the passphrase will be read from stdin.
557 In this case, reading will not stop at newline characters.
559 With LUKS, passphrases supplied via \-\-key-file are always
560 the existing passphrases requested by a command, except in
561 the case of \fIluksFormat\fR where \-\-key-file is equivalent
562 to the positional key file argument.
564 If you want to set a new passphrase via key file, you have to
565 use a positional argument to \fIluksAddKey\fR.
567 See section \fBNOTES ON PASSPHRASE PROCESSING\fR for more information.
569 .B "\-\-keyfile-offset \fIvalue\fR"
570 Skip \fIvalue\fR bytes at the beginning of the key file.
571 Works with all commands that accepts key files.
573 .B "\-\-keyfile-size, \-l \fIvalue\fR"
574 Read a maximum of \fIvalue\fR bytes from the key file.
575 Default is to read the whole file up to the compiled-in
576 maximum that can be queried with \-\-help. Supplying more
577 data than the compiled-in maximum aborts the operation.
579 This option is useful
580 to cut trailing newlines, for example. If \-\-keyfile-offset
581 is also given, the size count starts after the offset.
582 Works with all commands that accepts key files.
584 .B "\-\-new-keyfile-offset \fIvalue\fR"
585 Skip \fIvalue\fR bytes at the start when
586 adding a new passphrase from key file with
589 .B "\-\-new-keyfile-size \fIvalue\fR"
590 Read a maximum of \fIvalue\fR bytes when adding
591 a new passphrase from key file with \fIluksAddKey\fR.
592 Default is to read the whole file up to the compiled-in
593 maximum length that can be queried with \-\-help.
594 Supplying more than the compiled in maximum aborts the
596 When \-\-new-keyfile-offset is also given, reading starts
599 .B "\-\-master-key-file"
600 Use a master key stored in a file.
602 For \fIluksFormat\fR this
603 allows creating a LUKS header with this specific
604 master key. If the master key was taken from an existing
605 LUKS header and all other parameters are the same,
606 then the new header decrypts the data encrypted with the
607 header the master key was taken from.
609 For \fIluksAddKey\fR this allows adding a new passphrase
610 without having to know an exiting one.
612 For \fIopen\fR this allows to open the LUKS device
613 without giving a passphrase.
615 .B "\-\-dump-master-key"
616 For \fIluksDump\fR this option includes the master key in the displayed
617 information. Use with care, as the master key can be used to
618 bypass the passphrases, see also option \-\-master-key-file.
623 For \fIluksFormat\fR these options define which kernel random number
624 generator will be used to create the master key (which is a
627 See \fBNOTES ON RANDOM NUMBER GENERATORS\fR for more
628 information. Use \fIcryptsetup \-\-help\fR
629 to show the compiled-in default random number generator.
631 \fBWARNING:\fR In a low-entropy situation (e.g. in an
632 embedded system), both selections are problematic.
633 Using /dev/urandom can lead to weak keys.
634 Using /dev/random can block a long time, potentially
635 forever, if not enough entropy can be harvested by
638 .B "\-\-key-slot, \-S <0-7>"
639 For LUKS operations that add key material, this options allows you
640 to specify which key slot is selected for the new key.
641 This option can be used for \fIluksFormat\fR,
642 and \fIluksAddKey\fR.
644 In addition, for \fIopen\fR, this option selects a
645 specific key-slot to compare the passphrase against.
646 If the given passphrase would only match a different key-slot,
649 .B "\-\-key-size, \-s <bits>"
650 Sets key size in bits. The argument has to be a multiple of
651 8. The possible key-sizes are limited by the cipher and
654 See /proc/crypto for more information. Note that key-size
655 in /proc/crypto is stated in bytes.
657 This option can be used for \fIopen \-\-type plain\fR or \fIluksFormat\fR.
658 All other LUKS actions will use the key-size specified in the LUKS header.
659 Use \fIcryptsetup \-\-help\fR to show the compiled-in defaults.
661 .B "\-\-size, \-b <number of 512 byte sectors>"
662 Force the size of the underlying device in sectors of 512 bytes.
663 This option is only relevant for the \fIopen\fR and \fIresize\fR
666 .B "\-\-offset, \-o <number of 512 byte sectors>"
667 Start offset in the backend device in 512-byte sectors.
668 This option is only relevant for the \fIopen\fR action with plain
669 or loopaes device types.
671 .B "\-\-skip, \-p <number of 512 byte sectors>"
672 How many sectors of the encrypted data to skip at the beginning.
673 This option is only relevant for the \fIopen\fR action with plain
674 or loopaes device types.
676 This is different from the \-\-offset options with respect to
677 the sector numbers used in IV calculation.
678 Using \-\-offset will shift the IV calculation by the same negative amount.
679 Hence, if \-\-offset \fIn\fR, sector \fIn\fR will get a sector
680 number of \fI0\fR for the IV calculation.
681 Using \-\-skip causes sector \fIn\fR to also be the first sector
682 of the mapped device, but with its number for IV generation is \fIn\fR.
684 .B "\-\-readonly, \-r"
685 set up a read-only mapping.
688 Creates an additional mapping for one common
689 ciphertext device. Arbitrary mappings are supported.
690 This option is only relevant for the
691 \fIopen \-\-type plain\fR action. Use \-\-offset, \-\-size and \-\-skip to
692 specify the mapped area.
694 .B "\-\-iter-time, \-i <number of milliseconds>"
695 The number of milliseconds to spend with PBKDF2 passphrase processing.
696 This option is only relevant for LUKS operations that set or change
697 passphrases, such as \fIluksFormat\fR or \fIluksAddKey\fR.
698 Specifying 0 as parameter selects the compiled-in default.
700 .B "\-\-batch-mode, \-q"
701 Suppresses all confirmation questions. Use with care!
703 If the \-y option is not specified, this option also switches off
704 the passphrase verification for \fIluksFormat\fR.
706 .B "\-\-timeout, \-t <number of seconds>"
707 The number of seconds to wait before timeout on passphrase input
708 via terminal. It is relevant every time a passphrase is asked,
709 for example for \fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR.
710 It has no effect if used in conjunction with \-\-key-file.
712 This option is useful when the system
713 should not stall if the user does not input a passphrase,
714 e.g. during boot. The default is a value of 0 seconds,
715 which means to wait forever.
718 How often the input of the passphrase shall be retried.
719 This option is relevant
720 every time a passphrase is asked, for example for
721 \fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR.
722 The default is 3 tries.
724 .B "\-\-align-payload <number of 512 byte sectors>"
725 Align payload at a boundary of \fIvalue\fR 512-byte sectors.
726 This option is relevant for \fIluksFormat\fR.
728 If not specified, cryptsetup tries to use the topology info
729 provided by kernel for the underlying device to get optimal alignment.
730 If not available (or the calculated value is a multiple of the default)
731 data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte sectors).
733 For a detached LUKS header this option specifies the offset on the
734 data device. See also the \-\-header option.
736 .B "\-\-uuid=\fIUUID\fR"
737 Use the provided \fIUUID\fR for the \fIluksFormat\fR command
738 instead of generating new one. Changes the existing UUID when
739 used with the \fIluksUUID\fR command.
741 The UUID must be provided in the standard UUID format,
742 e.g. 12345678-1234-1234-1234-123456789abc.
744 .B "\-\-allow-discards\fR"
745 Allow the use of discard (TRIM) requests for device.
746 This option is only relevant for \fIopen\fR action.
748 \fBWARNING:\fR This command can have a negative security impact
749 because it can make filesystem-level operations visible on
750 the physical device. For example, information leaking
751 filesystem type, used space, etc. may be extractable from
752 the physical device if the discarded blocks can be located
753 later. If in doubt, do no use it.
755 A kernel version of 3.1 or later is needed. For earlier kernels
756 this option is ignored.
758 .B "\-\-test-passphrase\fR"
759 Do not activate device, just verify passphrase.
760 This option is only relevant for \fIopen\fR action (the device
761 mapping name is not mandatory if this option is used).
763 .B "\-\-header\fR <device or file storing the LUKS header>"
764 Use a detached (separated) metadata device or file where the
765 LUKS header is stored. This options allows to store ciphertext
766 and LUKS header on different devices.
768 This option is only relevant for LUKS devices and can be
769 used with the \fIluksFormat\fR, \fIopen\fR, \fIluksSuspend\fR,
770 \fIluksResume\fR, \fIstatus\fR and \fIresize\fR commands.
772 For \fIluksFormat\fR with a file name as argument to \-\-header,
773 it has to exist and be large enough to contain the LUKS header.
774 See the cryptsetup FAQ for header size calculation.
776 For other commands that change the LUKS header (e.g. \fIluksAddKey\fR),
777 specify the device or file with the LUKS header directly as the
780 If used with \fIluksFormat\fR, the \-\-align-payload option is taken
781 as absolute sector alignment on ciphertext device and can be zero.
783 \fBWARNING:\fR There is no check whether the ciphertext device specified
784 actually belongs to the header given. In fact you can specify an
785 arbitrary device as the ciphertext device for \fIopen\fR
786 with the \-\-header option. Use with care.
788 .B "\-\-force-password\fR"
789 Do not use password quality checking for new LUKS passwords.
791 This option applies only to \fIluksFormat\fR, \fIluksAddKey\fR and
792 \fIluksChangeKey\fR and is ignored if cryptsetup is built without
793 password quality checking support.
795 For more info about password quality check, see manual page
796 for \fBpwquality.conf(5)\fR.
799 Show the program version.
802 Show short option help.
805 Show help text and default parameters.
807 Cryptsetup returns 0 on success and a non-zero value on error.
809 Error codes are: 1 wrong parameters, 2 no permission (bad passphrase),
810 3 out of memory, 4 wrong device specified, 5 device already exists
812 .SH NOTES ON PASSPHRASE PROCESSING FOR PLAIN MODE
813 Note that no iterated hashing or salting is done in plain mode.
814 If hashing is done, it is a single direct hash. This means that
815 low-entropy passphrases are easy to attack in plain mode.
817 \fBFrom a terminal\fR: The passphrase is read until the
818 first newline, i.e. '\\n'.
819 The input without the newline character is processed with
820 the default hash or the hash specified with \-\-hash.
821 The has result will be truncated to the key size
822 of the used cipher, or the size specified with \-s.
824 \fBFrom stdin\fR: Reading will continue until a newline (or until
825 the maximum input size is reached), with the trailing newline
826 stripped. The maximum input size is defined by the same
827 compiled-in default as for the maximum key file size and can
828 be overwritten using \-\-keyfile-size option.
830 The data read will be hashed with the default hash
831 or the hash specified with \-\-hash.
832 The has result will be truncated to the key size
833 of the used cipher, or the size specified with \-s.
835 Note that if \-\-key-file=- is used for reading the key
836 from stdin, trailing newlines are not stripped from the input.
838 If "plain" is used as argument to \-\-hash, the input
839 data will not be hashed. Instead, it will be zero padded (if
840 shorter than the key size) or truncated (if longer than the
841 key size) and used directly as the binary key. This is useful for
842 directly specifying a binary key.
843 No warning will be given if the amount of data read from stdin is
844 less than the key size.
846 \fBFrom a key file\fR: It will be truncated to the
847 key size of the used cipher or the size given by \-s
848 and directly used as binary key.
849 if the key file is shorter than the key, cryptsetup
850 will quit with an error.
852 .SH NOTES ON PASSPHRASE PROCESSING FOR LUKS
853 LUKS uses PBKDF2 to protect against dictionary attacks
854 and to give some protection to low-entropy passphrases
855 (see RFC 2898 and the cryptsetup FAQ).
857 \fBFrom a terminal\fR: The passphrase is read until the
858 first newline and then processed by PBKDF2 without
859 the newline character.
862 LUKS will read passphrases from stdin up to the
863 first newline character or the compiled-in
864 maximum key file length. If \-\-keyfile-size is
865 given, it is ignored.
868 The complete keyfile is read up to the compiled-in
869 maximum size. Newline characters do not terminate the
870 input. The \-\-keyfile-size option can be used to limit
873 \fBPassphrase processing\fR:
874 Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat),
875 the user may specify how much the time the passphrase processing
876 should consume. The time is used to determine the iteration count
877 for PBKDF2 and higher times will offer better protection for
878 low-entropy passphrases, but open will take longer to
879 complete. For passphrases that have entropy higher than the
880 used key length, higher iteration times will not increase security.
882 The default setting of one second is sufficient for most
883 practical cases. The only exception is a low-entropy
884 passphrase used on a slow device.
885 .SH INCOHERENT BEHAVIOR FOR INVALID PASSPHRASES/KEYS
886 LUKS checks for a valid passphrase when an encrypted partition
887 is unlocked. The behavior of plain dm-crypt is different.
888 It will always decrypt with the passphrase given. If the
889 given passphrase is wrong, the device mapped by plain
890 dm-crypt will essentially still contain encrypted data and
892 .SH NOTES ON SUPPORTED CIPHERS, MODES, HASHES AND KEY SIZES
893 The available combinations of ciphers, modes, hashes and key sizes
894 depend on kernel support. See /proc/crypto for a list of available
895 options. You might need to load additional kernel crypto modules
896 in order to get more options.
898 For the \-\-hash option, if the crypto backend is libgcrypt,
899 then all algorithms supported by the gcrypt library are available.
900 For other crypto backends some algorithms may be missing.
901 .SH NOTES ON PASSPHRASES
902 Mathematics can't be bribed. Make sure you keep your passphrases safe.
903 There are a few nice tricks for constructing a fallback, when suddenly
904 out of the blue, your brain refuses to cooperate.
905 These fallbacks need LUKS, as it's only possible with LUKS
906 to have multiple passphrases. Still, if your attacker model does
907 not prevent it, storing your passphrase in a sealed envelope somewhere
908 may be a good idea as well.
909 .SH NOTES ON RANDOM NUMBER GENERATORS
910 Random Number Generators (RNG) used in cryptsetup are always the
911 kernel RNGs without any modifications or additions to data stream
914 There are two types of randomness cryptsetup/LUKS needs. One type
915 (which always uses /dev/urandom) is used for salts, the AF splitter
916 and for wiping deleted keyslots.
918 The second type is used for the volume (master) key. You can switch
919 between using /dev/random and /dev/urandom here, see
920 \fP\-\-use-random\fR and \fP\-\-use-urandom\fR
921 options. Using /dev/random on a system without enough entropy sources
922 can cause \fPluksFormat\fR to block until the requested amount of
923 random data is gathered. In a low-entropy situation (embedded system),
924 this can take a very long time and potentially forever. At the same
925 time, using /dev/urandom in a low-entropy situation will
926 produce low-quality keys. This is a serious problem, but solving
927 it is out of scope for a mere man-page.
928 See \fPurandom(4)\fR for more information.
929 .SH NOTES ON LOOPBACK DEVICE USE
930 Cryptsetup is usually used directly on a block device (disk
931 partition or LVM volume). However, if the device argument is a
932 file, cryptsetup tries to allocate a loopback device
933 and map it into this file. This mode requires Linux kernel 2.6.25
934 or more recent which supports the loop autoclear flag (loop device is
935 cleared on last close automatically). Of course, you can
936 always map a file to a loop-device manually. See the
937 cryptsetup FAQ for an example.
939 When device mapping is active, you can see the loop backing file in
940 the status command output. Also see losetup(8).
941 .SH DEPRECATED ACTIONS
943 The \fIreload\fR action is no longer supported.
944 Please use \fIdmsetup(8)\fR if you need to
945 directly manipulate with the device mapping table.
947 The \fIluksDelKey\fR was replaced with \fIluksKillSlot\fR.
950 Report bugs, including ones in the documentation, on
951 the cryptsetup mailing list at <dm-crypt@saout.de>
952 or in the 'Issues' section on LUKS website.
953 Please attach the output of the failed command with the
954 \-\-debug option added.
956 cryptsetup originally written by Christophe Saout <christophe@saout.de>
958 The LUKS extensions and original man page were written by
959 Clemens Fruhwirth <clemens@endorphin.org>.
961 Man page extensions by Milan Broz <gmazyland@gmail.com>.
963 Man page rewrite and extension by Arno Wagner <arno@wagner.name>.
965 Copyright \(co 2004 Christophe Saout
967 Copyright \(co 2004-2006 Clemens Fruhwirth
969 Copyright \(co 2009-2012 Red Hat, Inc.
971 Copyright \(co 2009-2012 Milan Broz
973 Copyright \(co 2012 Arno Wagner
975 This is free software; see the source for copying conditions. There is NO
976 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
978 The LUKS website at \fBhttp://code.google.com/p/cryptsetup/\fR
980 The cryptsetup FAQ, contained in the distribution package and
982 \fBhttp://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions\fR
984 The cryptsetup mailing list and list archive, see FAQ entry 1.6.
986 The LUKS on-disk format specification available at
987 \fBhttp://code.google.com/p/cryptsetup/wiki/Specification\fR