1CRYPTSETUP-OPEN(8)           Maintenance Commands           CRYPTSETUP-OPEN(8)
2
3
4

NAME

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

SYNOPSIS

12       cryptsetup open --type <device_type> [<options>] <device> <name>
13

DESCRIPTION

15       Opens (creates a mapping with) <name> backed by device <device>.
16
17       Device type can be plain, luks (default), luks1, luks2, loopaes or
18       tcrypt.
19
20       For backward compatibility there are open command aliases:
21
22       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
29       <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
34   PLAIN
35       open --type plain <device> <name>
36       plainOpen <device> <name> (old syntax)
37       create <name> <device> (OBSOLETE syntax)
38
39       Opens (creates a mapping with) <name> backed by device <device>.
40
41       <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
46       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
51   LUKS
52       open <device> <name>
53       open --type <luks1|luks2> <device> <name> (explicit version request)
54       luksOpen <device> <name> (old syntax)
55
56       Opens the LUKS device <device> and sets up a mapping <name> after
57       successful verification of the supplied passphrase.
58
59       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
63       <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
70   loopAES
71       open --type loopaes <device> <name> --key-file <keyfile>
72       loopaesOpen <device> <name> --key-file <keyfile> (old syntax)
73
74       Opens the loop-AES <device> and sets up a mapping <name>.
75
76       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
81       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
87       Use --keyfile-size to specify the proper key length if needed.
88
89       Use --offset to specify device offset. Note that the units need to be
90       specified in number of 512 byte sectors.
91
92       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
96       Use --hash to override the default hash function for passphrase hashing
97       (otherwise it is detected according to key size).
98
99       <options> can be [--cipher, --key-file, --keyfile-size,
100       --keyfile-offset, --key-size, --offset, --skip, --hash, --readonly,
101       --allow-discards, --refresh].
102
103   TrueCrypt and VeraCrypt
104       open --type tcrypt <device> <name>
105       tcryptOpen <device> <name> (old syntax)
106
107       Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) <device> and sets
108       up a mapping <name>.
109
110       <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
116       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
120       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
125       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
129       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
134   BitLocker
135       open --type bitlk <device> <name>
136       bitlkOpen <device> <name> (old syntax)
137
138       Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping
139       <name>.
140
141       <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

OPTIONS

146       --type <device-type>
147           Specifies required device type, for more info read BASIC ACTIONS
148           section in cryptsetup(8).
149
150       --hash, -h <hash-spec>
151           Specifies the passphrase hash. Applies to plain and loopaes device
152           types only.
153
154           For tcrypt device type, it restricts checked PBKDF2 variants when
155           looking for header.
156
157       --cipher, -c <cipher-spec>
158           Set the cipher specification string for plain device type.
159
160           For tcrypt device type it restricts checked cipher chains when
161           looking for header.
162
163           cryptsetup --help shows the compiled-in defaults.
164
165           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
169           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
173       --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
179       --key-file, -d name
180           Read the passphrase from file.
181
182           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
185           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
190           See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for
191           more information.
192
193       --keyfile-offset value
194           Skip value bytes at the beginning of the key file.
195
196       --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
202           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
206       --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
210       --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
215           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
220       --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
224           See /proc/crypto for more information. Note that key-size in
225           /proc/crypto is stated in bytes.
226
227           This option can be used for plain device type only.
228
229       --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
233       --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
237       --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
242           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
246       --device-size size[units]
247           Instead of real device size, use specified value. Usable only with
248           plain device type.
249
250           If no unit suffix is specified, the size is in bytes.
251
252           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
256       --readonly, -r
257           set up a read-only mapping.
258
259       --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
265       --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
270           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
274       --tries, -T
275           How often the input of the passphrase shall be retried. The default
276           is 3 tries.
277
278       --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
283           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
289           A kernel version of 3.1 or later is needed. For earlier kernels,
290           this option is ignored.
291
292       --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
297           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
301       --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
308           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
312       --perf-no_read_workqueue, --perf-no_write_workqueue
313           Bypass dm-crypt internal workqueue and process read or write
314           requests synchronously.
315
316           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
320       --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
324       --header <device or file storing the LUKS header>
325           Specify detached (separated) metadata device or file where the
326           header is stored.
327
328           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
333       --disable-external-tokens
334           Disable loading of plugins for external LUKS2 tokens.
335
336       --disable-locks
337           Disable lock protection for metadata on disk. This option is valid
338           only for LUKS2 and ignored for other formats.
339
340           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
344       --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
349       --token-id
350           Specify what token to use. If omitted, all available tokens will be
351           checked before proceeding further with passphrase prompt.
352
353       --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
358       --token-type
359           Restrict tokens eligible for operation to specific token type
360           (name). Mostly useful when no --token-id is specified.
361
362       --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
367           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
371           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
375       --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
380           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
384       --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
391           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
395           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
400       --refresh
401           Refreshes an active device with new set of parameters. See
402           cryptsetup-refresh(8) for more details.
403
404       --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
410       --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
414       --veracrypt
415           This option is ignored as VeraCrypt compatible mode is supported by
416           default.
417
418       --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
423       --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
427       --serialize-memory-hard-pbkdf
428           Use a global lock to serialize unlocking of keyslots using
429           memory-hard PBKDF.
430
431           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
436           DO NOT USE this switch until you are implementing boot environment
437           with parallel devices activation!
438
439       --batch-mode, -q
440           Suppresses all confirmation questions. Use with care!
441
442           If the --verify-passphrase option is not specified, this option
443           also switches off the passphrase verification.
444
445       --debug or --debug-json
446           Run in debug mode with full diagnostic logs. Debug output lines are
447           always prefixed by #.
448
449           If --debug-json is used, additional LUKS2 JSON data structures are
450           printed.
451
452       --version, -V
453           Show the program version.
454
455       --usage
456           Show short option help.
457
458       --help, -?
459           Show help text and default parameters.
460

REPORTING BUGS

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
466       Please attach output of the failed command with --debug option added.
467

SEE ALSO

469       Cryptsetup FAQ
470       <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
471
472       cryptsetup(8), integritysetup(8) and veritysetup(8)
473

CRYPTSETUP

475       Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
476
477
478
479cryptsetup 2.5.0                  2022-07-28                CRYPTSETUP-OPEN(8)
Impressum