1CRYPTSETUP(8) Maintenance Commands CRYPTSETUP(8)
2
6 cryptsetup - setup cryptographic volumes for dm-crypt (including LUKS
7 extension)
8
10 cryptsetup <options> <action> <action args>
11
13 cryptsetup is used to conveniently setup dm-crypt managed device-mapper
14 mappings. For basic (plain) dm-crypt mappings, there are four opera‐
15 tions.
16
18 These strings are valid for <action>, followed by their <action args>:
19 create <name> <device>
21 creates a mapping with <name> backed by device <device>.
23 <options> can be [--hash, --cipher, --verify-passphrase, --key-
25 file, --key-size, --offset, --skip, --readonly]
26 remove <name>
28 removes an existing mapping <name>.
30 status <name>
32 reports the status for the mapping <name>.
34 resize <name>
36 resizes an active mapping <name>.
38 If --size (in sectors) is not specified, the size of the under‐
40 lying block device is used.
41
43 LUKS, Linux Unified Key Setup, is a standard for hard disk encryption.
44 It standardizes a partition header, as well as the format of the bulk
45 data. LUKS can manage multiple passwords, that can be revoked effec‐
46 tively and that are protected against dictionary attacks with PBKDF2.
47 These are valid LUKS actions:
49 luksFormat <device> [<key file>]
51 initializes a LUKS partition and sets the initial key, either
53 via prompting or via <key file>.
54 <options> can be [--cipher, --verify-passphrase, --key-size,
56 --key-slot, --key-file (takes precedence over optional second
57 argument)].
58 luksOpen <device> <name>
61 opens the LUKS partition <device> and sets up a mapping <name>
63 after successful verification of the supplied key material
64 (either via key file by --key-file, or via prompting).
65 <options> can be [--key-file, --readonly].
67 luksClose <name>
69 identical to remove.
71 luksSuspend <name>
73 suspends active device (all IO operations are frozen) and wipes
75 encryption key from kernel. Kernel version 2.6.19 or later is
76 required.
77 After that operation you have to use luksResume to reinstate
79 encryption key (and resume device) or luksClose to remove mapped
80 device.
81 WARNING: never try to suspend device where is the cryptsetup
83 binary itself.
84 luksResume <name>
86 Resumes suspended device and reinstates encryption key. You will
88 need provide passphrase identical to luksOpen command (using
89 prompting or key file).
90 <options> can be [--key-file]
92 luksAddKey <device> [<new key file>]
94 add a new key file/passphrase. An existing passphrase or key
96 file (via --key-file) must be supplied. The key file with the
97 new material is supplied as a positional argument.
98 <options> can be [--key-file, --key-slot].
100 luksRemoveKey <device> [<key file>]
102 remove supplied key or key file from LUKS device
104 luksKillSlot <device> <key slot number>
106 wipe key with number <key slot> from LUKS device. A remaining
108 passphrase or key file (via --key-file) must be supplied.
109 <options> can be [--key-file].
111 luksDelKey <device> <key slot number>
113 identical to luksKillSlot, but deprecated action name.
115 luksUUID <device>
117 print UUID, if <device> has a LUKS header.
119 isLuks <device>
121 returns true, if <device> is a LUKS partition. Otherwise, false.
123 luksDump <device>
125 dumps the header information of a LUKS partition.
127 luksHeaderBackup <device> --header-backup-file <file>
129 Stores binary backup of LUKS header and keyslot areas.
131 WARNING: Please note that with this backup file (and old
133 passphrase knowledge) you can decrypt data even if old
134 passphrase was wiped from real device.
135 Also note that anti-forensic splitter is not used during manipu‐
137 lation with backup file.
138 luksHeaderRestore <device> --header-backup-file <file>
140 Restores binary backup of LUKS header and keyslot areas from
142 specified file.
143 WARNING: All the keyslot areas are overwritten, only active
145 keyslots form backup file are available after issuing this com‐
146 mand.
147 This command allows restoring header if device do not contain
149 LUKS header or if the master key size and data offset in LUKS
150 header on device match the backup file.
151 For more information about LUKS, see http://code.google.com/p/crypt‐
153 setup/wiki/Specification
154
157 --verbose, -v
158 Print more verbose messages.
159 --debug
161 Run in debug mode with full diagnostic logs.
162 --hash, -h
164 For create action specifies hash to use for password hashing.
165 For luksFormat action specifies hash used in LUKS key setup
167 scheme and volume key digest.
168 WARNING: setting hash other than sha1 causes LUKS device incom‐
170 patible with older version of cryptsetup.
171 The hash string is passed to libgcrypt, so all hashes accepted
173 by gcrypt are supported. Default is set during compilation,
174 compatible values with old version of cryptsetup are "ripemd160"
175 for create action and "sha1" for luksFormat.
176 Use cryptsetup --help to show defaults.
178 --cipher, -c
180 set cipher specification string.
181 Default mode is configurable during compilation, you can see
183 compiled-in default using cryptsetup --help. If not changed,
184 the default is for plain dm-crypt and LUKS mappings "aes-cbc-
185 essiv:sha256".
186 For pre-2.6.10 kernels, use "aes-plain" as they don't understand
188 the new cipher spec strings. To use ESSIV, use "aes-cbc-
189 essiv:sha256".
190 For XTS mode, kernel version 2.6.24 or more recent is required.
192 Use "aes-xts-plain" cipher specification and set key size to 256
193 (or 512) bits (see -s option).
194 --verify-passphrase, -y
196 query for passwords twice. Useful when creating a (regular) map‐
197 ping for the first time, or when running luksFormat.
198 --key-file, -d
200 use file as key material.
201 With LUKS, key material supplied in key files via -d are always
203 used for existing passphrases, except in luksFormat action where
204 -d is equivalent to positional key file argument. If you want
205 to set a new key via a key file, you have to use a positional
206 arg to luksAddKey.
207 If the key file is "-", stdin will be used. With the "-" key
209 file reading will not stop when new line character is detected.
210 See section NOTES ON PASSWORD PROCESSING for more information.
211 --master-key-file
213 Use pre-generated master key stored in file. For luksFormat it
214 allows LUKS header reformatting with the same master key (if all
215 other parameters are the same existing encrypted data remains
216 intact).
217 For luksAddKey it allows adding new passphrase with only master
219 key knowledge.
220 --key-slot, -S
222 For LUKS operations that add key material, this options allows
223 to you specify which key slot is selected for the new key. This
224 option can be used for luksFormat and luksAddKey.
225 --key-size, -s
227 set key size in bits.
228 Has to be a multiple of 8 bits. The key size is limited by the
230 used cipher. See output of /proc/crypto for more information.
231 Can be used for create or luksFormat, all other LUKS actions
232 will use key-size specified by the LUKS header. Default is set
233 during compilation, if not changed it is 256 bits.
234 Use cryptsetup --help to show defaults.
236 For luksOpen this option specifies number of bits read from the
238 key-file (default is exhaustive read from key-file).
239 --size, -b
241 force the size of the underlying device in sectors. This option
242 is only relevant for create and resize action.
243 --offset, -o
245 start offset in the backend device. This option is only rele‐
246 vant for create action.
247 --skip, -p
249 how many sectors of the encrypted data to skip at the beginning.
250 This is different from the --offset options with respect to IV
251 calculations. Using --offset will shift the IV calculation by
252 the same negative amount. Hence, if --offset n, sector n will be
253 the first sector on the mapping with IV 0. Using --skip would
254 have resulted in sector n being the first sector also, but with
255 IV n. This option is only relevant for create action.
256 --readonly
258 set up a read-only mapping.
259 --iter-time, -i
261 The number of milliseconds to spend with PBKDF2 password pro‐
262 cessing. This option is only relevant to the LUKS operations as
263 luksFormat or luksAddKey.
264 --batch-mode, -q
266 Do not ask for confirmation. Use with care! This option is only
267 relevant for luksFormat, luksAddKey, luksRemoveKey or luksKill‐
268 Slot.
269 --timeout, -t
271 The number of seconds to wait before timeout. This option is
272 relevant every time a password is asked, like create, luksOpen,
273 luksFormat or luksAddKey. It has no effect if used in conjunc‐
274 tion with --key-file.
275 --tries, -T
277 How often the input of the passphrase shall be retried. This
278 option is relevant every time a password is asked, like create,
279 luksOpen, luksFormat or luksAddKey. The default is 3 tries.
280 --align-payload=value
282 Align payload at a boundary of value 512-byte sectors. This
283 option is relevant for luksFormat. If your block device lives
284 on a RAID, it is useful to align the filesystem at full stripe
285 boundaries so it can take advantage of the RAID's geometry. See
286 for instance the sunit and swidth options in the mkfs.xfs manual
287 page. By default, the payload is aligned at an 8 sector (4096
288 byte) boundary.
289 --version
291 Show the version.
292
295 From a terminal: Password processing is new-line sensitive, meaning the
296 reading will stop after encountering \n. It will process the read mate‐
297 rial (without newline) with the default hash or the hash given by
298 --hash. After hashing, it will be cropped to the key size given by -s.
299 From stdin: Reading will continue until EOF (so using e.g. /dev/random
301 as stdin will not work), with the trailing newline stripped. After that
302 the read data will be hashed with the default hash or the hash given by
303 --hash and the result will be cropped to the keysize given by -s. If
304 "plain" is used as an argument to the hash option, the input data will
305 not be hashed. Instead, it will be zero padded (if shorter than the
306 keysize) or truncated (if longer than the keysize) and used directly as
307 the key. No warning will be given if the amount of data read from stdin
308 is less than the keysize.
309 From a key file: It will be cropped to the size given by -s. If there
311 is insufficient key material in the key file, cryptsetup will quit with
312 an error.
313 If --key-file=- is used for reading the key from stdin, no trailing
315 newline is stripped from the input. Without that option, cryptsetup
316 strips trailing newlines from stdin input.
317
319 LUKS uses PBKDF2 to protect against dictionary attacks (see RFC 2898).
320 LUKS will always do an exhaustive password reading. Hence, password can
322 not be read from /dev/random, /dev/zero or any other stream that does
323 not terminate.
324 For any password creation action (luksAddKey, or luksFormat), the user
326 may specify how much the time the password processing should consume.
327 Increasing the time will lead to a more secure password, but also will
328 take luksOpen longer to complete. The default setting of one second is
329 sufficient for good security.
330
332 LUKS checks for a valid password or key when an encrypted partition is
333 unlocked. Thus the luksOpen action fails with invalid password or key,
334 contrary to the plain dm-crypt create action.
335 Please also be sure that you are using the same keyboard and language
337 setting as during device format.
338
340 The available combinations of ciphers, modes, hashes and key sizes
341 depend on kernel support. See /proc/crypto for a list of available
342 options. You might need to load additional kernel crypto modules in
343 order to get more options.
344 For --hash option all algorithms supported by gcrypt library are avail‐
346 able.
347
349 Mathematics can't be bribed. Make sure you keep your passwords safe.
350 There are a few nice tricks for constructing a fallback, when suddenly
351 out of (or after being) blue, your brain refuses to cooperate. These
352 fallbacks are possible with LUKS, as it's only possible with LUKS to
353 have multiple passwords.
354
356 cryptsetup is written by Christophe Saout <christophe@saout.de>
357 LUKS extensions, and man page by Clemens Fruhwirth <clemens@endor‐
358 phin.org>
359
361 To read images created with SuSE Linux 9.2's loop_fish2 use --cipher
362 twofish-cbc-null -s 256 -h sha512, for images created with even older
363 SuSE Linux use --cipher twofish-cbc-null -s 192 -h ripemd160:20
364
367 reload <name> <device>
368 modifies an active mapping <name>. Same options as for create.
370 WARNING: Do not use this for LUKS devices, as the semantics are
371 identical to the create action, which are totally incompatible
372 with the LUKS key setup.
373 This action is deprected because it proved to be rarely useful.
375 It is uncommon to change the underlying device, key, or offset
376 on the fly. In case, you really want to do this, you certainly
377 know what you are doing and then you are probably better off
378 with the swiss knive tool for device mapper, namely dmsetup. It
379 provides you with the same functionality, see dmsetup reload.
380 luksDelKey <device> <key slot number>
382 identical to luksKillSlot, but deprecated action name. This
384 option was renamed, as we introduced luksRemoveKey, a softer
385 method for disabling password slots. To make a clear distinction
386 that luksDelKey was more brutal than luksRemoveKey
387 --non-exclusive
389 This option is ignored. Non-exclusive access to the same block
391 device can cause data corruption thus this mode is no longer
392 supported by cryptsetup.
393
396 Report bugs to <dm-crypt@saout.de> or Issues section on LUKS website.
397 Please attach output of failed command with added --debug option.
398
400 Copyright © 2004 Christophe Saout
401 Copyright © 2004-2006 Clemens Fruhwirth
402 Copyright © 2009-2010 Red Hat, Inc.
403 This is free software; see the source for copying conditions. There is
405 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
406 PURPOSE.
407
409 dm-crypt website, http://www.saout.de/misc/dm-crypt/
410 LUKS website, http://code.google.com/p/cryptsetup/
412 dm-crypt TWiki, http://www.saout.de/tikiwiki/tiki-index.php
414cryptsetup CRYPTSETUP(8)