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, cryptsetup-fvault2Open - open an encrypted device and create
9       a mapping with a 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 LUKS2 tokens unprotected by PIN.
60       If such token does not exist (or fails to unlock keyslot) and also the
61       passphrase is not supplied via --key-file, the command prompts for
62       passphrase interactively.
63
64       If there is valid LUKS2 token but it requires PIN to unlock assigned
65       keyslot, it is not used unless one of following options is added:
66       --token-only, --token-type where type matches desired PIN protected
67       token or --token-id with id matching PIN protected token.
68
69       <options> can be [--key-file, --keyfile-offset, --keyfile-size,
70       --readonly, --test-passphrase, --allow-discards, --header, --key-slot,
71       --volume-key-file, --token-id, --token-only, --token-type,
72       --disable-external-tokens, --disable-keyring, --disable-locks, --type,
73       --refresh, --serialize-memory-hard-pbkdf, --unbound, --tries,
74       --timeout, --verify-passphrase, --persistent].
75
76   loopAES
77       open --type loopaes <device> <name> --key-file <keyfile>
78       loopaesOpen <device> <name> --key-file <keyfile> (old syntax)
79
80       Opens the loop-AES <device> and sets up a mapping <name>.
81
82       If the key file is encrypted with GnuPG, then you have to use
83       --key-file=- and decrypt it before use, e.g., like this:
84       gpg --decrypt <keyfile> | cryptsetup loopaesOpen --key-file=- <device>
85       <name>
86
87       WARNING: The loop-AES extension cannot use the direct input of the key
88       file on the real terminal because the keys are separated by end-of-line
89       and only part of the multi-key file would be read.
90       If you need it in script, just use the pipe redirection:
91       echo $keyfile | cryptsetup loopaesOpen --key-file=- <device> <name>
92
93       Use --keyfile-size to specify the proper key length if needed.
94
95       Use --offset to specify device offset. Note that the units need to be
96       specified in number of 512 byte sectors.
97
98       Use --skip to specify the IV offset. If the original device used an
99       offset and but did not use it in IV sector calculations, you have to
100       explicitly use --skip 0 in addition to the offset parameter.
101
102       Use --hash to override the default hash function for passphrase hashing
103       (otherwise it is detected according to key size).
104
105       <options> can be [--cipher, --key-file, --keyfile-size,
106       --keyfile-offset, --key-size, --offset, --skip, --hash, --readonly,
107       --allow-discards, --refresh].
108
109   TrueCrypt and VeraCrypt
110       open --type tcrypt <device> <name>
111       tcryptOpen <device> <name> (old syntax)
112
113       Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) <device> and sets
114       up a mapping <name>.
115
116       <options> can be [--key-file, --tcrypt-hidden, --tcrypt-system,
117       --tcrypt-backup, --readonly, --test-passphrase, --allow-discards,
118       --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim,
119       --veracrypt-query-pim, --header, --cipher, --hash, --tries, --timeout,
120       --verify-passphrase].
121
122       The keyfile parameter allows a combination of file content with the
123       passphrase and can be repeated. Note that using keyfiles is compatible
124       with TCRYPT and is different from LUKS keyfile logic.
125
126       If --cipher or --hash options are used, only cipher chains or PBKDF2
127       variants with the specified hash algorithms are checked. This could
128       speed up unlocking the device (but also it reveals some information
129       about the container).
130
131       If you use --header in combination with hidden or system options, the
132       header file must contain specific headers on the same positions as the
133       original encrypted container.
134
135       WARNING: Option --allow-discards cannot be combined with option
136       --tcrypt-hidden. For normal mapping, it can cause the destruction of
137       hidden volume (hidden volume appears as unused space for outer volume
138       so this space can be discarded).
139
140   BitLocker
141       open --type bitlk <device> <name>
142       bitlkOpen <device> <name> (old syntax)
143
144       Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping
145       <name>.
146
147       <options> can be [--key-file, --keyfile-offset, --keyfile-size,
148       --key-size, --readonly, --test-passphrase, --allow-discards
149       --volume-key-file, --tries, --timeout, --verify-passphrase].
150
151   FileVault2
152       open --type fvault2 <device> <name>
153       fvault2Open <device> <name> (old syntax)
154
155       Opens the FVAULT2 (a FileVault2 compatible) <device> and sets up a
156       mapping <name>.
157
158       <options> can be [--key-file, --keyfile-offset, --keyfile-size,
159       --key-size, --readonly, --test-passphrase, --allow-discards
160       --volume-key-file, --tries, --timeout, --verify-passphrase].
161

OPTIONS

163       --type <device-type>
164           Specifies required device type, for more info read BASIC ACTIONS
165           section in cryptsetup(8).
166
167       --hash, -h <hash-spec>
168           Specifies the passphrase hash. Applies to plain and loopaes device
169           types only.
170
171           For tcrypt device type, it restricts checked PBKDF2 variants when
172           looking for header.
173
174       --cipher, -c <cipher-spec>
175           Set the cipher specification string for plain device type.
176
177           For tcrypt device type it restricts checked cipher chains when
178           looking for header.
179
180           cryptsetup --help shows the compiled-in defaults.
181
182           If a hash is part of the cipher specification, then it is used as
183           part of the IV generation. For example, ESSIV needs a hash
184           function, while "plain64" does not and hence none is specified.
185
186           For XTS mode you can optionally set a key size of 512 bits with the
187           -s option. Key size for XTS mode is twice that for other modes for
188           the same security level.
189
190       --verify-passphrase, -y
191           When interactively asking for a passphrase, ask for it twice and
192           complain if both inputs do not match. Advised when creating a plain
193           type mapping for the first time. Ignored on input from file or
194           stdin.
195
196       --key-file, -d name
197           Read the passphrase from file.
198
199           If the name given is "-", then the passphrase will be read from
200           stdin. In this case, reading will not stop at newline characters.
201
202           NOTE: With plain device type, the passphrase obtained via
203           --key-file option is passed directly in dm-crypt. Unlike the
204           interactive mode (stdin) where digest (--hash option) of the
205           passphrase is passed in dm-crypt instead.
206
207           See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for
208           more information.
209
210       --keyfile-offset value
211           Skip value bytes at the beginning of the key file.
212
213       --keyfile-size, -l value
214           Read a maximum of value bytes from the key file. The default is to
215           read the whole file up to the compiled-in maximum that can be
216           queried with --help. Supplying more data than the compiled-in
217           maximum aborts the operation.
218
219           This option is useful to cut trailing newlines, for example. If
220           --keyfile-offset is also given, the size count starts after the
221           offset.
222
223       --volume-key-file, --master-key-file (OBSOLETE alias)
224           Use a volume key stored in a file. This allows one to open luks and
225           bitlk device types without giving a passphrase.
226
227       --key-slot, -S <0-N>
228           This option selects a specific key-slot to compare the passphrase
229           against. If the given passphrase would only match a different
230           key-slot, the operation fails.
231
232           The maximum number of key slots depends on the LUKS version. LUKS1
233           can have up to 8 key slots. LUKS2 can have up to 32 key slots based
234           on key slot area size and key size, but a valid key slot ID can
235           always be between 0 and 31 for LUKS2.
236
237       --key-size, -s bits
238           Sets key size in bits. The argument has to be a multiple of 8. The
239           possible key-sizes are limited by the cipher and mode used.
240
241           See /proc/crypto for more information. Note that key-size in
242           /proc/crypto is stated in bytes.
243
244           This option can be used for plain device type only.
245
246       --size, -b <number of 512 byte sectors>
247           Set the size of the device in sectors of 512 bytes. Usable only
248           with plain device type.
249
250       --offset, -o <number of 512 byte sectors>
251           Start offset in the backend device in 512-byte sectors. This option
252           is only relevant with plain or loopaes device types.
253
254       --skip, -p <number of 512 byte sectors>
255           Start offset used in IV calculation in 512-byte sectors (how many
256           sectors of the encrypted data to skip at the beginning). This
257           option is only relevant with plain or loopaes device types.
258
259           Hence, if --offset n, and --skip s, sector n (the first sector of
260           the encrypted device) will get a sector number of s for the IV
261           calculation.
262
263       --device-size size[units]
264           Instead of real device size, use specified value. Usable only with
265           plain device type.
266
267           If no unit suffix is specified, the size is in bytes.
268
269           Unit suffix can be S for 512 byte sectors, K/M/G/T (or
270           KiB,MiB,GiB,TiB) for units with 1024 base or KB/MB/GB/TB for 1000
271           base (SI scale).
272
273       --readonly, -r
274           set up a read-only mapping.
275
276       --shared
277           Creates an additional mapping for one common ciphertext device.
278           Arbitrary mappings are supported. This option is only relevant for
279           the plain device type. Use --offset, --size and --skip to specify
280           the mapped area.
281
282       --timeout, -t <number of seconds>
283           The number of seconds to wait before timeout on passphrase input
284           via terminal. It is relevant every time a passphrase is asked. It
285           has no effect if used in conjunction with --key-file.
286
287           This option is useful when the system should not stall if the user
288           does not input a passphrase, e.g. during boot. The default is a
289           value of 0 seconds, which means to wait forever.
290
291       --tries, -T
292           How often the input of the passphrase shall be retried. The default
293           is 3 tries.
294
295       --allow-discards
296           Allow the use of discard (TRIM) requests for the device. This is
297           also not supported for LUKS2 devices with data integrity
298           protection.
299
300           WARNING: This command can have a negative security impact because
301           it can make filesystem-level operations visible on the physical
302           device. For example, information leaking filesystem type, used
303           space, etc. may be extractable from the physical device if the
304           discarded blocks can be located later. If in doubt, do not use it.
305
306           A kernel version of 3.1 or later is needed. For earlier kernels,
307           this option is ignored.
308
309       --perf-same_cpu_crypt
310           Perform encryption using the same cpu that IO was submitted on. The
311           default is to use an unbound workqueue so that encryption work is
312           automatically balanced between available CPUs.
313
314           NOTE: This option is available only for low-level dm-crypt
315           performance tuning, use only if you need a change to default
316           dm-crypt behaviour. Needs kernel 4.0 or later.
317
318       --perf-submit_from_crypt_cpus
319           Disable offloading writes to a separate thread after encryption.
320           There are some situations where offloading write bios from the
321           encryption threads to a single thread degrades performance
322           significantly. The default is to offload write bios to the same
323           thread.
324
325           NOTE: This option is available only for low-level dm-crypt
326           performance tuning, use only if you need a change to default
327           dm-crypt behaviour. Needs kernel 4.0 or later.
328
329       --perf-no_read_workqueue, --perf-no_write_workqueue
330           Bypass dm-crypt internal workqueue and process read or write
331           requests synchronously.
332
333           NOTE: These options are available only for low-level dm-crypt
334           performance tuning, use only if you need a change to default
335           dm-crypt behaviour. Needs kernel 5.9 or later.
336
337       --test-passphrase
338           Do not activate the device, just verify passphrase. The device
339           mapping name is not mandatory if this option is used.
340
341       --header <device or file storing the LUKS header>
342           Specify detached (separated) metadata device or file where the
343           header is stored.
344
345           WARNING: There is no check whether the ciphertext device specified
346           actually belongs to the header given. In fact, you can specify an
347           arbitrary device as the ciphertext device with the --header option.
348           Use with care.
349
350       --disable-external-tokens
351           Disable loading of plugins for external LUKS2 tokens.
352
353       --disable-locks
354           Disable lock protection for metadata on disk. This option is valid
355           only for LUKS2 and ignored for other formats.
356
357           WARNING: Do not use this option unless you run cryptsetup in a
358           restricted environment where locking is impossible to perform
359           (where /run directory cannot be used).
360
361       --disable-keyring
362           Do not load volume key in kernel keyring and store it directly in
363           the dm-crypt target instead. This option is supported only for the
364           LUKS2 type.
365
366       --token-id
367           Specify what token to use and allow token PIN prompt to take
368           precedence over interative keyslot passphrase prompt. If omitted,
369           all available tokens (not protected by PIN) will be checked before
370           proceeding further with passphrase prompt.
371
372       --token-only
373           Do not proceed further with action if token based keyslot unlock
374           failed. Without the option, action asks for passphrase to proceed
375           further.
376
377           It allows LUKS2 tokens protected by PIN to take precedence over
378           interactive keyslot passphrase prompt.
379
380       --token-type type
381           Restrict tokens eligible for operation to specific token type.
382           Mostly useful when no --token-id is specified.
383
384           It allows LUKS2 type tokens protected by PIN to take precedence
385           over interactive keyslot passphrase prompt.
386
387       --sector-size bytes
388           Set encryption sector size for use with plain device type. It must
389           be power of two and in range 512 - 4096 bytes. The default mode is
390           512 bytes.
391
392           Note that if sector size is higher than underlying device hardware
393           sector, using this option can increase risk on incomplete sector
394           writes during a power fail.
395
396           Increasing sector size from 512 bytes to 4096 bytes can provide
397           better performance on most of the modern storage devices and also
398           with some hw encryption accelerators.
399
400       --iv-large-sectors
401           Count Initialization Vector (IV) in larger sector size (if set)
402           instead of 512 bytes sectors. This option can be used only with
403           plain device type.
404
405           NOTE: This option does not have any performance or security impact,
406           use it only for accessing incompatible existing disk images from
407           other systems that require this option.
408
409       --persistent
410           If used with LUKS2 devices and activation commands like open or
411           refresh, the specified activation flags are persistently written
412           into metadata and used next time automatically even for normal
413           activation. (No need to use cryptab or other system configuration
414           files.)
415
416           If you need to remove a persistent flag, use --persistent without
417           the flag you want to remove (e.g. to disable persistently stored
418           discard flag, use --persistent without --allow-discards).
419
420           Only --allow-discards, --perf-same_cpu_crypt,
421           --perf-submit_from_crypt_cpus, --perf-no_read_workqueue,
422           --perf-no_write_workqueue and --integrity-no-journal can be stored
423           persistently.
424
425       --refresh
426           Refreshes an active device with new set of parameters. See
427           cryptsetup-refresh(8) for more details.
428
429       --unbound
430           Allowed only together with --test-passphrase parameter, it allows
431           one to test passphrase for unbound LUKS2 keyslot. Otherwise,
432           unbound keyslot passphrase can be tested only when specific keyslot
433           is selected via --key-slot parameter.
434
435       --tcrypt-hidden, --tcrypt-system, --tcrypt-backup
436           Specify which TrueCrypt on-disk header will be used to open the
437           device. See TCRYPT section in cryptsetup(8) for more info.
438
439       --veracrypt
440           This option is ignored as VeraCrypt compatible mode is supported by
441           default.
442
443       --disable-veracrypt
444           This option can be used to disable VeraCrypt compatible mode (only
445           TrueCrypt devices are recognized). Only for TCRYPT extension. See
446           TCRYPT section in cryptsetup(8) for more info.
447
448       --veracrypt-pim, --veracrypt-query-pim
449           Use a custom Personal Iteration Multiplier (PIM) for VeraCrypt
450           device. See TCRYPT section in cryptsetup(8) for more info.
451
452       --serialize-memory-hard-pbkdf
453           Use a global lock to serialize unlocking of keyslots using
454           memory-hard PBKDF.
455
456           NOTE: This is (ugly) workaround for a specific situation when
457           multiple devices are activated in parallel and system instead of
458           reporting out of memory starts unconditionally stop processes using
459           out-of-memory killer.
460
461           DO NOT USE this switch until you are implementing boot environment
462           with parallel devices activation!
463
464       --batch-mode, -q
465           Suppresses all confirmation questions. Use with care!
466
467           If the --verify-passphrase option is not specified, this option
468           also switches off the passphrase verification.
469
470       --debug or --debug-json
471           Run in debug mode with full diagnostic logs. Debug output lines are
472           always prefixed by #.
473
474           If --debug-json is used, additional LUKS2 JSON data structures are
475           printed.
476
477       --version, -V
478           Show the program version.
479
480       --usage
481           Show short option help.
482
483       --help, -?
484           Show help text and default parameters.
485

REPORTING BUGS

487       Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
488       in Issues project section
489       <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
490
491       Please attach output of the failed command with --debug option added.
492

SEE ALSO

494       Cryptsetup FAQ
495       <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
496
497       cryptsetup(8), integritysetup(8) and veritysetup(8)
498

CRYPTSETUP

500       Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
501
502
503
504cryptsetup 2.6.1                  2023-02-10                CRYPTSETUP-OPEN(8)
Impressum