1CRYPTSETUP-OPEN(8) Maintenance Commands CRYPTSETUP-OPEN(8)
2
6 cryptsetup-open, cryptsetup-create, cryptsetup-plainOpen, cryptsetup-
7 luksOpen, cryptsetup-loopaesOpen, cryptsetup-tcryptOpen, cryptsetup-
8 bitlkOpen - open an encrypted device and create a mapping with a
9 specified name
10
12 cryptsetup open --type <device_type> [<options>] <device> <name>
13
15 Opens (creates a mapping with) <name> backed by device <device>.
16 Device type can be plain, luks (default), luks1, luks2, loopaes or
18 tcrypt.
19 For backward compatibility there are open command aliases:
21 create (argument-order <name> <device>): open --type plain
23 plainOpen: open --type plain
24 luksOpen: open --type luks
25 loopaesOpen: open --type loopaes
26 tcryptOpen: open --type tcrypt
27 bitlkOpen: open --type bitlk
28 <options> are type specific and are described below for individual
30 device types. For create, the order of the <name> and <device> options
31 is inverted for historical reasons, all other aliases use the standard
32 <device> <name> order.
33 PLAIN
35 open --type plain <device> <name>
36 plainOpen <device> <name> (old syntax)
37 create <name> <device> (OBSOLETE syntax)
38 Opens (creates a mapping with) <name> backed by device <device>.
40 <options> can be [--hash, --cipher, --verify-passphrase, --sector-size,
42 --key-file, --keyfile-size, --keyfile-offset, --key-size, --offset,
43 --skip, --device-size, --size, --readonly, --shared, --allow-discards,
44 --refresh, --timeout, --verify-passphrase, --iv-large-sectors].
45 Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the raw
47 encrypted device /dev/sda10 to the mapped (decrypted) device
48 /dev/mapper/e1, which can then be mounted, fsck-ed or have a filesystem
49 created on it.
50 LUKS
52 open <device> <name>
53 open --type <luks1|luks2> <device> <name> (explicit version request)
54 luksOpen <device> <name> (old syntax)
55 Opens the LUKS device <device> and sets up a mapping <name> after
57 successful verification of the supplied passphrase.
58 First, the passphrase is searched in LUKS tokens. If it’s not found in
60 any token and also the passphrase is not supplied via --key-file, the
61 command prompts for it interactively.
62 <options> can be [--key-file, --keyfile-offset, --keyfile-size,
64 --readonly, --test-passphrase, --allow-discards, --header, --key-slot,
65 --volume-key-file, --token-id, --token-only, --token-type,
66 --disable-external-tokens, --disable-keyring, --disable-locks, --type,
67 --refresh, --serialize-memory-hard-pbkdf, --unbound, --tries,
68 --timeout, --verify-passphrase, --persistent].
69 loopAES
71 open --type loopaes <device> <name> --key-file <keyfile>
72 loopaesOpen <device> <name> --key-file <keyfile> (old syntax)
73 Opens the loop-AES <device> and sets up a mapping <name>.
75 If the key file is encrypted with GnuPG, then you have to use
77 --key-file=- and decrypt it before use, e.g., like this:
78 gpg --decrypt <keyfile> | cryptsetup loopaesOpen --key-file=- <device>
79 <name>
80 WARNING: The loop-AES extension cannot use the direct input of the key
82 file on the real terminal because the keys are separated by end-of-line
83 and only part of the multi-key file would be read.
84 If you need it in script, just use the pipe redirection:
85 echo $keyfile | cryptsetup loopaesOpen --key-file=- <device> <name>
86 Use --keyfile-size to specify the proper key length if needed.
88 Use --offset to specify device offset. Note that the units need to be
90 specified in number of 512 byte sectors.
91 Use --skip to specify the IV offset. If the original device used an
93 offset and but did not use it in IV sector calculations, you have to
94 explicitly use --skip 0 in addition to the offset parameter.
95 Use --hash to override the default hash function for passphrase hashing
97 (otherwise it is detected according to key size).
98 <options> can be [--cipher, --key-file, --keyfile-size,
100 --keyfile-offset, --key-size, --offset, --skip, --hash, --readonly,
101 --allow-discards, --refresh].
102 TrueCrypt and VeraCrypt
104 open --type tcrypt <device> <name>
105 tcryptOpen <device> <name> (old syntax)
106 Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) <device> and sets
108 up a mapping <name>.
109 <options> can be [--key-file, --tcrypt-hidden, --tcrypt-system,
111 --tcrypt-backup, --readonly, --test-passphrase, --allow-discards,
112 --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim,
113 --veracrypt-query-pim, --header, --cipher, --hash, --tries, --timeout,
114 --verify-passphrase].
115 The keyfile parameter allows a combination of file content with the
117 passphrase and can be repeated. Note that using keyfiles is compatible
118 with TCRYPT and is different from LUKS keyfile logic.
119 If --cipher or --hash options are used, only cipher chains or PBKDF2
121 variants with the specified hash algorithms are checked. This could
122 speed up unlocking the device (but also it reveals some information
123 about the container).
124 If you use --header in combination with hidden or system options, the
126 header file must contain specific headers on the same positions as the
127 original encrypted container.
128 WARNING: Option --allow-discards cannot be combined with option
130 --tcrypt-hidden. For normal mapping, it can cause the destruction of
131 hidden volume (hidden volume appears as unused space for outer volume
132 so this space can be discarded).
133 BitLocker
135 open --type bitlk <device> <name>
136 bitlkOpen <device> <name> (old syntax)
137 Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping
139 <name>.
140 <options> can be [--key-file, --keyfile-offset, --keyfile-size,
142 --key-size, --readonly, --test-passphrase, --allow-discards
143 --volume-key-file, --tries, --timeout, --verify-passphrase].
144
146 --type <device-type>
147 Specifies required device type, for more info read BASIC ACTIONS
148 section in cryptsetup(8).
149 --hash, -h <hash-spec>
151 Specifies the passphrase hash. Applies to plain and loopaes device
152 types only.
153 For tcrypt device type, it restricts checked PBKDF2 variants when
155 looking for header.
156 --cipher, -c <cipher-spec>
158 Set the cipher specification string for plain device type.
159 For tcrypt device type it restricts checked cipher chains when
161 looking for header.
162 cryptsetup --help shows the compiled-in defaults.
164 If a hash is part of the cipher specification, then it is used as
166 part of the IV generation. For example, ESSIV needs a hash
167 function, while "plain64" does not and hence none is specified.
168 For XTS mode you can optionally set a key size of 512 bits with the
170 -s option. Key size for XTS mode is twice that for other modes for
171 the same security level.
172 --verify-passphrase, -y
174 When interactively asking for a passphrase, ask for it twice and
175 complain if both inputs do not match. Advised when creating a plain
176 type mapping for the first time. Ignored on input from file or
177 stdin.
178 --key-file, -d name
180 Read the passphrase from file.
181 If the name given is "-", then the passphrase will be read from
183 stdin. In this case, reading will not stop at newline characters.
184 NOTE: With plain device type, the passphrase obtained via
186 --key-file option is passed directly in dm-crypt. Unlike the
187 interactive mode (stdin) where digest (--hash option) of the
188 passphrase is passed in dm-crypt instead.
189 See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for
191 more information.
192 --keyfile-offset value
194 Skip value bytes at the beginning of the key file.
195 --keyfile-size, -l value
197 Read a maximum of value bytes from the key file. The default is to
198 read the whole file up to the compiled-in maximum that can be
199 queried with --help. Supplying more data than the compiled-in
200 maximum aborts the operation.
201 This option is useful to cut trailing newlines, for example. If
203 --keyfile-offset is also given, the size count starts after the
204 offset.
205 --volume-key-file, --master-key-file (OBSOLETE alias)
207 Use a volume key stored in a file. This allows one to open luks and
208 bitlk device types without giving a passphrase.
209 --key-slot, -S <0-N>
211 This option selects a specific key-slot to compare the passphrase
212 against. If the given passphrase would only match a different
213 key-slot, the operation fails.
214 The maximum number of key slots depends on the LUKS version. LUKS1
216 can have up to 8 key slots. LUKS2 can have up to 32 key slots based
217 on key slot area size and key size, but a valid key slot ID can
218 always be between 0 and 31 for LUKS2.
219 --key-size, -s bits
221 Sets key size in bits. The argument has to be a multiple of 8. The
222 possible key-sizes are limited by the cipher and mode used.
223 See /proc/crypto for more information. Note that key-size in
225 /proc/crypto is stated in bytes.
226 This option can be used for plain device type only.
228 --size, -b <number of 512 byte sectors>
230 Set the size of the device in sectors of 512 bytes. Usable only
231 with plain device type.
232 --offset, -o <number of 512 byte sectors>
234 Start offset in the backend device in 512-byte sectors. This option
235 is only relevant with plain or loopaes device types.
236 --skip, -p <number of 512 byte sectors>
238 Start offset used in IV calculation in 512-byte sectors (how many
239 sectors of the encrypted data to skip at the beginning). This
240 option is only relevant with plain or loopaes device types.
241 Hence, if --offset n, and --skip s, sector n (the first sector of
243 the encrypted device) will get a sector number of s for the IV
244 calculation.
245 --device-size size[units]
247 Instead of real device size, use specified value. Usable only with
248 plain device type.
249 If no unit suffix is specified, the size is in bytes.
251 Unit suffix can be S for 512 byte sectors, K/M/G/T (or
253 KiB,MiB,GiB,TiB) for units with 1024 base or KB/MB/GB/TB for 1000
254 base (SI scale).
255 --readonly, -r
257 set up a read-only mapping.
258 --shared
260 Creates an additional mapping for one common ciphertext device.
261 Arbitrary mappings are supported. This option is only relevant for
262 the plain device type. Use --offset, --size and --skip to specify
263 the mapped area.
264 --timeout, -t <number of seconds>
266 The number of seconds to wait before timeout on passphrase input
267 via terminal. It is relevant every time a passphrase is asked. It
268 has no effect if used in conjunction with --key-file.
269 This option is useful when the system should not stall if the user
271 does not input a passphrase, e.g. during boot. The default is a
272 value of 0 seconds, which means to wait forever.
273 --tries, -T
275 How often the input of the passphrase shall be retried. The default
276 is 3 tries.
277 --allow-discards
279 Allow the use of discard (TRIM) requests for the device. This is
280 also not supported for LUKS2 devices with data integrity
281 protection.
282 WARNING: This command can have a negative security impact because
284 it can make filesystem-level operations visible on the physical
285 device. For example, information leaking filesystem type, used
286 space, etc. may be extractable from the physical device if the
287 discarded blocks can be located later. If in doubt, do not use it.
288 A kernel version of 3.1 or later is needed. For earlier kernels,
290 this option is ignored.
291 --perf-same_cpu_crypt
293 Perform encryption using the same cpu that IO was submitted on. The
294 default is to use an unbound workqueue so that encryption work is
295 automatically balanced between available CPUs.
296 NOTE: This option is available only for low-level dm-crypt
298 performance tuning, use only if you need a change to default
299 dm-crypt behaviour. Needs kernel 4.0 or later.
300 --perf-submit_from_crypt_cpus
302 Disable offloading writes to a separate thread after encryption.
303 There are some situations where offloading write bios from the
304 encryption threads to a single thread degrades performance
305 significantly. The default is to offload write bios to the same
306 thread.
307 NOTE: This option is available only for low-level dm-crypt
309 performance tuning, use only if you need a change to default
310 dm-crypt behaviour. Needs kernel 4.0 or later.
311 --perf-no_read_workqueue, --perf-no_write_workqueue
313 Bypass dm-crypt internal workqueue and process read or write
314 requests synchronously.
315 NOTE: These options are available only for low-level dm-crypt
317 performance tuning, use only if you need a change to default
318 dm-crypt behaviour. Needs kernel 5.9 or later.
319 --test-passphrase
321 Do not activate the device, just verify passphrase. The device
322 mapping name is not mandatory if this option is used.
323 --header <device or file storing the LUKS header>
325 Specify detached (separated) metadata device or file where the
326 header is stored.
327 WARNING: There is no check whether the ciphertext device specified
329 actually belongs to the header given. In fact, you can specify an
330 arbitrary device as the ciphertext device with the --header option.
331 Use with care.
332 --disable-external-tokens
334 Disable loading of plugins for external LUKS2 tokens.
335 --disable-locks
337 Disable lock protection for metadata on disk. This option is valid
338 only for LUKS2 and ignored for other formats.
339 WARNING: Do not use this option unless you run cryptsetup in a
341 restricted environment where locking is impossible to perform
342 (where /run directory cannot be used).
343 --disable-keyring
345 Do not load volume key in kernel keyring and store it directly in
346 the dm-crypt target instead. This option is supported only for the
347 LUKS2 type.
348 --token-id
350 Specify what token to use. If omitted, all available tokens will be
351 checked before proceeding further with passphrase prompt.
352 --token-only
354 Do not proceed further with action if token based keyslot unlock
355 failed. Without the option, action asks for passphrase to proceed
356 further.
357 --token-type
359 Restrict tokens eligible for operation to specific token type
360 (name). Mostly useful when no --token-id is specified.
361 --sector-size bytes
363 Set encryption sector size for use with plain device type. It must
364 be power of two and in range 512 - 4096 bytes. The default mode is
365 512 bytes.
366 Note that if sector size is higher than underlying device hardware
368 sector, using this option can increase risk on incomplete sector
369 writes during a power fail.
370 Increasing sector size from 512 bytes to 4096 bytes can provide
372 better performance on most of the modern storage devices and also
373 with some hw encryption accelerators.
374 --iv-large-sectors
376 Count Initialization Vector (IV) in larger sector size (if set)
377 instead of 512 bytes sectors. This option can be used only with
378 plain device type.
379 NOTE: This option does not have any performance or security impact,
381 use it only for accessing incompatible existing disk images from
382 other systems that require this option.
383 --persistent
385 If used with LUKS2 devices and activation commands like open or
386 refresh, the specified activation flags are persistently written
387 into metadata and used next time automatically even for normal
388 activation. (No need to use cryptab or other system configuration
389 files.)
390 If you need to remove a persistent flag, use --persistent without
392 the flag you want to remove (e.g. to disable persistently stored
393 discard flag, use --persistent without --allow-discards).
394 Only --allow-discards, --perf-same_cpu_crypt,
396 --perf-submit_from_crypt_cpus, --perf-no_read_workqueue,
397 --perf-no_write_workqueue and --integrity-no-journal can be stored
398 persistently.
399 --refresh
401 Refreshes an active device with new set of parameters. See
402 cryptsetup-refresh(8) for more details.
403 --unbound
405 Allowed only together with --test-passphrase parameter, it allows
406 one to test passphrase for unbound LUKS2 keyslot. Otherwise,
407 unbound keyslot passphrase can be tested only when specific keyslot
408 is selected via --key-slot parameter.
409 --tcrypt-hidden, --tcrypt-system, --tcrypt-backup
411 Specify which TrueCrypt on-disk header will be used to open the
412 device. See TCRYPT section in cryptsetup(8) for more info.
413 --veracrypt
415 This option is ignored as VeraCrypt compatible mode is supported by
416 default.
417 --disable-veracrypt
419 This option can be used to disable VeraCrypt compatible mode (only
420 TrueCrypt devices are recognized). Only for TCRYPT extension. See
421 TCRYPT section in cryptsetup(8) for more info.
422 --veracrypt-pim, --veracrypt-query-pim
424 Use a custom Personal Iteration Multiplier (PIM) for VeraCrypt
425 device. See TCRYPT section in cryptsetup(8) for more info.
426 --serialize-memory-hard-pbkdf
428 Use a global lock to serialize unlocking of keyslots using
429 memory-hard PBKDF.
430 NOTE: This is (ugly) workaround for a specific situation when
432 multiple devices are activated in parallel and system instead of
433 reporting out of memory starts unconditionally stop processes using
434 out-of-memory killer.
435 DO NOT USE this switch until you are implementing boot environment
437 with parallel devices activation!
438 --batch-mode, -q
440 Suppresses all confirmation questions. Use with care!
441 If the --verify-passphrase option is not specified, this option
443 also switches off the passphrase verification.
444 --debug or --debug-json
446 Run in debug mode with full diagnostic logs. Debug output lines are
447 always prefixed by #.
448 If --debug-json is used, additional LUKS2 JSON data structures are
450 printed.
451 --version, -V
453 Show the program version.
454 --usage
456 Show short option help.
457 --help, -?
459 Show help text and default parameters.
460
462 Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
463 in Issues project section
464 <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
465 Please attach output of the failed command with --debug option added.
467
469 Cryptsetup FAQ
470 <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
471 cryptsetup(8), integritysetup(8) and veritysetup(8)
473
475 Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
476cryptsetup 2.5.0 2022-07-28 CRYPTSETUP-OPEN(8)