mirror of
https://gitlab.com/cryptsetup/cryptsetup.git
synced 2025-12-05 16:00:05 +01:00
c66c520e26
Move all notes and warnings to description text. Refine some small clarification. Do not use NOTE/WARNING unless there is a serious reason (data loss).
145 lines
7.8 KiB
Plaintext
145 lines
7.8 KiB
Plaintext
= 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>.
|
|
|
|
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>*.
|
|
|
|
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>.
|
|
|
|
The --key-file option allows a combination of file content with the passphrase
|
|
The --key-file option can be repeated.
|
|
Note that using keyfiles 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.
|
|
|
|
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).
|
|
|
|
*<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].
|
|
|
|
=== BitLocker
|
|
*open --type bitlk <device> <name>* +
|
|
bitlkOpen <device> <name> (old syntax)
|
|
|
|
Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping <name>.
|
|
|
|
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.
|
|
|
|
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase].
|
|
|
|
=== 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[]
|