NAME
cryptsetup-open, cryptsetup-create, cryptsetup-plainOpen, cryptsetup-luksOpen, cryptsetup-loopaesOpen, cryptsetup-tcryptOpen, cryptsetup-bitlkOpen, cryptsetup-fvault2Open - open an encrypted device and create a mapping with a specified nameSYNOPSIS
cryptsetup open --type <device_type> [<options>] <device> <name>DESCRIPTION
Opens (creates a mapping with) <name> backed by device <device>.PLAIN
open --type plain <device> <name>LUKS
open <device> <name>loopAES
open --type loopaes <device> <name> --key-file <keyfile>TrueCrypt and VeraCrypt
open --type tcrypt <device> <name>BitLocker
open --type bitlk <device> <name>FileVault2
open --type fvault2 <device> <name>OPTIONS
--type <device-type>Specifies required device type, for more info
read BASIC ACTIONS section in cryptsetup(8).
Specifies the passphrase hash. Applies to
plain and loopaes device types only.
For tcrypt device type, it restricts checked PBKDF2 variants when looking
for header.
Set the cipher specification string for
plain device type.
For tcrypt device type it restricts checked cipher chains when looking
for header.
cryptsetup --help shows the compiled-in defaults.
If a hash is part of the cipher specification, then it is used as part of the IV
generation. For example, ESSIV needs a hash function, while
"plain64" does not and hence none is specified.
For XTS mode you can optionally set a key size of 512 bits with the -s option.
Key size for XTS mode is twice that for other modes for the same security
level.
When interactively asking for a passphrase,
ask for it twice and complain if both inputs do not match. Advised when
creating a plain type mapping for the first time. Ignored on input from
file or stdin.
Read the passphrase from file.
If the name given is "-", then the passphrase will be read from stdin.
In this case, reading will not stop at newline characters.
NOTE: With plain device type, the passphrase obtained via
--key-file option is passed directly in dm-crypt. Unlike the interactive mode
(stdin) where digest (--hash option) of the passphrase is passed in dm-crypt
instead.
See section NOTES ON PASSPHRASE PROCESSING in cryptsetup(8) for
more information.
Skip value bytes at the beginning of
the key file.
Read a maximum of value bytes from the
key file. The default is to read the whole file up to the compiled-in maximum
that can be queried with --help. Supplying more data than the compiled-in
maximum aborts the operation.
This option is useful to cut trailing newlines, for example. If --keyfile-offset
is also given, the size count starts after the offset.
Use a volume key stored in a file. This allows
one to open luks and bitlk device types without giving a
passphrase.
This option selects a specific key-slot to
compare the passphrase against. If the given passphrase would only match a
different key-slot, the operation fails.
The maximum number of key slots depends on the LUKS version. LUKS1 can have up
to 8 key slots. LUKS2 can have up to 32 key slots based on key slot area size
and key size, but a valid key slot ID can always be between 0 and 31 for
LUKS2.
Sets key size in bits. The argument has
to be a multiple of 8. The possible key-sizes are limited by the cipher and
mode used.
See /proc/crypto for more information. Note that key-size in /proc/crypto is
stated in bytes.
This option can be used for plain device type only.
Set the size of the device in sectors of 512
bytes. Usable only with plain device type.
Start offset in the backend device in 512-byte
sectors. This option is only relevant with plain or loopaes device
types.
Start offset used in IV calculation in
512-byte sectors (how many sectors of the encrypted data to skip at the
beginning). This option is only relevant with plain or loopaes device types.
Hence, if --offset n, and --skip s, sector n (the first
sector of the encrypted device) will get a sector number of s for the
IV calculation.
Instead of real device size, use specified
value. Usable only with plain device type.
If no unit suffix is specified, the size is in bytes.
Unit suffix can be S for 512 byte sectors, K/M/G/T (or KiB,MiB,GiB,TiB) for
units with 1024 base or KB/MB/GB/TB for 1000 base (SI scale).
set up a read-only mapping.
Creates an additional mapping for one common
ciphertext device. Arbitrary mappings are supported. This option is only
relevant for the plain device type. Use --offset, --size and --skip to
specify the mapped area.
The number of seconds to wait before timeout
on passphrase input via terminal. It is relevant every time a passphrase is
asked. It has no effect if used in conjunction with --key-file.
This option is useful when the system should not stall if the user does not
input a passphrase, e.g. during boot. The default is a value of 0 seconds,
which means to wait forever.
How often the input of the passphrase shall be
retried. The default is 3 tries.
Allow the use of discard (TRIM) requests for
the device. This is also not supported for LUKS2 devices with data integrity
protection.
WARNING: This command can have a negative security impact because it can
make filesystem-level operations visible on the physical device. For example,
information leaking filesystem type, used space, etc. may be extractable from
the physical device if the discarded blocks can be located later. If in doubt,
do not use it.
A kernel version of 3.1 or later is needed. For earlier kernels, this option is
ignored.
Perform encryption using the same cpu that IO
was submitted on. The default is to use an unbound workqueue so that
encryption work is automatically balanced between available CPUs.
NOTE: This option is available only for low-level dm-crypt performance
tuning, use only if you need a change to default dm-crypt behaviour. Needs
kernel 4.0 or later.
Disable offloading writes to a separate thread
after encryption. There are some situations where offloading write bios from
the encryption threads to a single thread degrades performance significantly.
The default is to offload write bios to the same thread.
NOTE: This option is available only for low-level dm-crypt performance
tuning, use only if you need a change to default dm-crypt behaviour. Needs
kernel 4.0 or later.
Bypass dm-crypt internal workqueue and process
read or write requests synchronously.
NOTE: These options are available only for low-level dm-crypt performance
tuning, use only if you need a change to default dm-crypt behaviour. Needs
kernel 5.9 or later.
Do not activate the device, just verify
passphrase. The device mapping name is not mandatory if this option is
used.
Specify detached (separated) metadata device
or file where the header is stored.
WARNING: There is no check whether the ciphertext device specified
actually belongs to the header given. In fact, you can specify an arbitrary
device as the ciphertext device with the --header option. Use with care.
Disable loading of plugins for external LUKS2
tokens.
Disable lock protection for metadata on disk.
This option is valid only for LUKS2 and ignored for other formats.
WARNING: Do not use this option unless you run cryptsetup in a restricted
environment where locking is impossible to perform (where /run directory
cannot be used).
Do not load volume key in kernel keyring and
store it directly in the dm-crypt target instead. This option is supported
only for the LUKS2 type.
Specify what token to use and allow token PIN
prompt to take precedence over interative keyslot passphrase prompt. If
omitted, all available tokens (not protected by PIN) will be checked before
proceeding further with passphrase prompt.
Do not proceed further with action if token
based keyslot unlock failed. Without the option, action asks for passphrase to
proceed further.
It allows LUKS2 tokens protected by PIN to take precedence over interactive
keyslot passphrase prompt.
Restrict tokens eligible for operation to
specific token type. Mostly useful when no --token-id is specified.
It allows LUKS2 type tokens protected by PIN to take precedence over
interactive keyslot passphrase prompt.
Set encryption sector size for use with
plain device type. It must be power of two and in range 512 - 4096
bytes. The default mode is 512 bytes.
Note that if sector size is higher than underlying device hardware sector, using
this option can increase risk on incomplete sector writes during a power fail.
Increasing sector size from 512 bytes to 4096 bytes can provide better
performance on most of the modern storage devices and also with some hw
encryption accelerators.
Count Initialization Vector (IV) in larger
sector size (if set) instead of 512 bytes sectors. This option can be used
only with plain device type.
NOTE: This option does not have any performance or security impact, use
it only for accessing incompatible existing disk images from other systems
that require this option.
If used with LUKS2 devices and activation
commands like open or refresh, the specified activation flags
are persistently written into metadata and used next time automatically even
for normal activation. (No need to use cryptab or other system configuration
files.)
If you need to remove a persistent flag, use --persistent without the
flag you want to remove (e.g. to disable persistently stored discard flag, use
--persistent without --allow-discards).
Only --allow-discards, --perf-same_cpu_crypt,
--perf-submit_from_crypt_cpus, --perf-no_read_workqueue,
--perf-no_write_workqueue and --integrity-no-journal can be
stored persistently.
Refreshes an active device with new set of
parameters. See cryptsetup-refresh(8) for more details.
Allowed only together with --test-passphrase
parameter, it allows one to test passphrase for unbound LUKS2 keyslot.
Otherwise, unbound keyslot passphrase can be tested only when specific keyslot
is selected via --key-slot parameter.
Specify which TrueCrypt on-disk header will be
used to open the device. See TCRYPT section in cryptsetup(8) for
more info.
This option is ignored as VeraCrypt compatible
mode is supported by default.
This option can be used to disable VeraCrypt
compatible mode (only TrueCrypt devices are recognized). Only for TCRYPT
extension. See TCRYPT section in cryptsetup(8) for more
info.
Use a custom Personal Iteration Multiplier
(PIM) for VeraCrypt device. See TCRYPT section in cryptsetup(8)
for more info.
Use a global lock to serialize unlocking of
keyslots using memory-hard PBKDF.
NOTE: This is (ugly) workaround for a specific situation when multiple
devices are activated in parallel and system instead of reporting out of
memory starts unconditionally stop processes using out-of-memory killer.
DO NOT USE this switch until you are implementing boot environment with
parallel devices activation!
Suppresses all confirmation questions. Use
with care!
If the --verify-passphrase option is not specified, this option also switches
off the passphrase verification.
Run in debug mode with full diagnostic logs.
Debug output lines are always prefixed by #.
If --debug-json is used, additional LUKS2 JSON data structures are
printed.
Show the program version.
Show short option help.
Show help text and default parameters.
REPORTING BUGS
Report bugs at cryptsetup <[email protected]>mailing or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.2023-12-18 | cryptsetup 2.6.1 |