cryptsetup/man/cryptsetup-open.8.adoc

= cryptsetup-open(8)
:doctype: manpage
:manmanual: Maintenance Commands
:mansource: cryptsetup {release-version}
:man-linkstyle: pass:[blue R < >]
:COMMON_OPTIONS:
:ACTION_OPEN:

== 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 name

== SYNOPSIS

*cryptsetup _open_ --type <device_type> [<options>] <device> <name>*

== DESCRIPTION
Opens (creates a mapping with) <name> backed by device <device>.

Device type can be _plain_, _luks_ (default), _luks1_, _luks2_, _loopaes_ or _tcrypt_.

For backward compatibility, there are *open* command aliases:

*create* (argument-order <name> <device>): open --type plain +
*plainOpen*: open --type plain +
*luksOpen*: open --type luks +
*loopaesOpen*: open --type loopaes +
*tcryptOpen*: open --type tcrypt +
*bitlkOpen*: open --type bitlk

*<options>* are type-specific and are described below for individual device types.
For *create*, the order of the <name> and <device> options is inverted for historical reasons; all other aliases use the standard *<device> <name>* order.

=== PLAIN
*open --type plain <device> <name>* --cipher <spec> --key-size <bits> --hash <alg> +
plainOpen <device> <name> (old syntax) +
create <name> <device> (OBSOLETE syntax)

Opens (creates a mapping with) <name> backed by device <device>.

*WARNING:* You should always specify options --cipher, --key-size and (if no keyfile or keyring is used) then also --hash to avoid incompatibility, as default values can differ in older cryptsetup versions. +

The plain format also allows retrieving a volume key from a kernel keyring specified by --volume-key-keyring.
The key in the kernel keyring must be configured before issuing cryptsetup commands, as cryptsetup does not upload any keys to the keyring in plain mode.
For subsequent commands (like resize), the user must ensure that the key in the keyring is unchanged.
Otherwise, reloading the key can cause data corruption after an unexpected key change.

*<options>* can be [--hash, --cipher, --sector-size, --key-file, --keyfile-size, --keyfile-offset, --key-size, --offset, --skip, --device-size, --size, --readonly, --shared, --allow-discards, --refresh, --timeout, --verify-passphrase, --iv-large-sectors, --volume-key-keyring].

*EXAMPLES:*

To map the encrypted device /dev/sda10 to the decrypted device /dev/mapper/e1, you can use:

*cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --hash sha256 /dev/sda10 e1*

The decrypted device can then be used as a normal block device to mount a filesystem.

To map a device with a volume key in the preconfigured trusted or encrypted keyring, you need to specify the keyring with the key and remove the hash specification, for example, to use *%trusted:mykey*:

*cryptsetup open --type plain /dev/sda10 e1 --volume-key-keyring=%trusted:mykey --cipher aes-xts-plain64 --key-size 256*

Note that the key size must match the preconfigured key in the keyring.

=== LUKS
*open <device> <name>* +
open --type <luks1|luks2> <device> <name> (explicit version request) +
luksOpen <device> <name> (old syntax)

Opens the LUKS device <device> and sets up a mapping <name> after successful verification of the supplied passphrase.

First, the passphrase is searched in LUKS2 tokens unprotected by PIN.
If such a token does not exist (or fails to unlock keyslot) and the passphrase is not supplied via --key-file, the command prompts for passphrase interactively.

If there is a valid LUKS2 token but it requires a PIN to unlock the assigned keyslot, it is not used unless one of the following options is added: --token-only,
--token-type where type matches the desired PIN-protected token or --token-id with id matching the PIN-protected token.

*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --readonly, --test-passphrase, --allow-discards, --header, --key-slot, --volume-key-file, --token-id, --token-only, --token-type, --disable-external-tokens, --disable-keyring, --disable-locks, --type, --refresh, --serialize-memory-hard-pbkdf, --unbound, --tries, --timeout, --verify-passphrase, --persistent, --volume-key-keyring, --link-vk-to-keyring, --external-tokens-path].

=== loopAES
*open --type loopaes <device> <name> --key-file <keyfile>* +
loopaesOpen <device> <name> --key-file <keyfile> (old syntax)

Opens the loop-AES <device> and sets up a mapping <name>.

If the key file is encrypted with GnuPG, then you have to use --key-file=- and decrypt it before use, e.g., like this: +
gpg --decrypt <keyfile> | cryptsetup loopaesOpen --key-file=- <device>
<name>

*WARNING:* The loop-AES extension cannot use the direct input of the key file on the real terminal because the keys are separated by end-of-line, and only part of the multi-key file would be read. +
If you need it in script, just use the pipe redirection: +
echo $keyfile | cryptsetup loopaesOpen --key-file=- <device> <name>

Use --keyfile-size to specify the proper key length if needed.

Use --offset to specify device offset.
Note that the units need to be specified in terms of 512-byte sectors.

Use --skip to specify the IV offset.
If the original device used an offset but did not use it in IV sector calculations, you must explicitly use --skip 0 in addition to the offset parameter.

Use --hash to override the default hash function for passphrase hashing (otherwise it is detected according to key size).

*<options>* can be [--cipher, --key-file, --keyfile-size, --keyfile-offset, --key-size, --offset, --skip, --hash, --readonly, --allow-discards, --refresh].

=== TrueCrypt and VeraCrypt
*open --type tcrypt <device> <name>* +
tcryptOpen <device> <name> (old syntax)

Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) <device> and sets
up a mapping <name>.

*<options>* can be [--key-file, --tcrypt-hidden, --tcrypt-system, --tcrypt-backup, --readonly, --test-passphrase, --allow-discards, --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim, --veracrypt-query-pim, --header, --cipher, --hash, --tries, --timeout, --verify-passphrase].

The keyfile parameter allows a combination of file content with the passphrase, which can be repeated.
Note that using keyfiles is compatible with TCRYPT and differs from LUKS keyfile logic.

If --cipher or --hash options are used, only cipher chains or PBKDF2 variants with the specified hash algorithms are checked.
This could speed up unlocking the device (but also reveals some information about the container).

If you use --header in combination with hidden or system options, the header file must contain specific headers in the same positions as the original encrypted container.

*WARNING:* Option --allow-discards cannot be combined with option --tcrypt-hidden.
For normal mapping, it can cause the destruction of hidden volume (hidden volume appears as unused space for outer volume, so this space can be discarded).

=== BitLocker
*open --type bitlk <device> <name>* +
bitlkOpen <device> <name> (old syntax)

Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping <name>.

*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase].

Note that --test-passphrase doesn't work with --volume-key-file because we cannot check whether the provided volume key is correct for this device.
When using --volume-key-file, the device will be opened even if the provided key is incorrect.

=== FileVault2
*open --type fvault2 <device> <name>* +
fvault2Open <device> <name> (old syntax)

Opens the FVAULT2 (a FileVault2 compatible) <device> and sets up a mapping <name>.

*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase].

include::man/common_options.adoc[]
include::man/common_footer.adoc[]