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