--- name: "cryptsetup-bitlkOpen" section: "8" platform: "linux" package: "cryptsetup-bin" version: "2:2.7.5-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/cryptsetup-open" --- # cryptsetup-bitlkOpen(8) open an encrypted device and create a mapping with a specified name Part of [cryptsetup-open(8)](/cryptsetup-open/8.md). ## 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 \ \[\\] \ \** ## DESCRIPTION *Opens (creates a mapping with) \ backed by device \.* *Device type can be plain, luks (default), luks1, luks2,* *loopaes or tcrypt.* *For backward compatibility there are* **open** *command aliases:* **create** *(argument-order \ \): open --type plain*\ **plainOpen***: open --type plain*\ **luksOpen***: open --type luks*\ **loopaesOpen***: open --type loopaes*\ **tcryptOpen***: open --type tcrypt*\ **bitlkOpen***: open --type bitlk* **\** *are type specific and are described below for individual* *device types. For* **create***, the order of the \ and \ options* *is inverted for historical reasons, all other aliases use the standard* **\ \** *order.* ### PLAIN **open --type plain \ \** *--cipher \ --key-size \ --hash \*\ *plainOpen \ \ (***old syntax***)*\ *create \ \ (***OBSOLETE syntax***)* *Opens (creates a mapping with) \ backed by device \.* **WARNING:** *You should always specify options* **--cipher***,* **--key-size** *and* *(if no keyfile is used) then also* **--hash** *to avoid incompatibility as* *default values can be different in older cryptsetup versions.*\ **\** *can be \[--hash, --cipher, --verify-passphrase, --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\].* *Example: 'cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --hash sha256 /dev/sda10 e1' maps the raw* *encrypted device /dev/sda10 to the mapped (decrypted) device* */dev/mapper/e1, which can then be mounted, fsck-ed or have a filesystem* *created on it.* ### LUKS **open \ \**\ *open --type \ \ \ (***explicit version request***)*\ *luksOpen \ \ (***old syntax***)* *Opens the LUKS device \ and sets up a mapping \ after* *successful verification of the supplied passphrase.* *First, the passphrase is searched in LUKS2 tokens unprotected by PIN.* *If such token does not exist (or fails to unlock keyslot) and* *also the passphrase is not supplied via --key-file, the command* *prompts for passphrase interactively.* *If there is valid LUKS2 token but it requires PIN to unlock assigned keyslot,* *it is not used unless one of following options is added: --token-only,* *--token-type where type matches desired PIN protected token or --token-id with id* *matching PIN protected token.* **\** *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 \ \ --key-file \**\ *loopaesOpen \ \ --key-file \ (***old syntax***)* *Opens the loop-AES \ and sets up a mapping \.* *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 \ \| cryptsetup loopaesOpen --key-file=- \* *\* **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=- \ \* *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 number of 512 byte sectors.* *Use* **--skip** *to specify the IV offset. If the original device used an* *offset and but did not use it in IV sector calculations, you have to* *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).* **\** *can be \[--cipher, --key-file, --keyfile-size, --keyfile-offset,* *--key-size, --offset, --skip, --hash, --readonly, --allow-discards, --refresh\].* ### TrueCrypt and VeraCrypt **open --type tcrypt \ \**\ *tcryptOpen \ \ (***old syntax***)* *Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) \ and sets* *up a mapping \.* **\** *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 and can be repeated. Note that using keyfiles is compatible* *with TCRYPT and is different 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 it reveals some information* *about the container).* *If you use* **--header** *in combination with hidden or system options, the* *header file must contain specific headers on 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 \ \**\ *bitlkOpen \ \ (***old syntax***)* *Opens the BITLK (a BitLocker compatible) \ and sets up a mapping* *\.* **\** *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* *or not. When using* **--volume-key-file** *the device will be opened even if* *the provided key is not correct.* ### FileVault2 **open --type fvault2 \ \**\ *fvault2Open \ \ (***old syntax***)* *Opens the FVAULT2 (a FileVault2 compatible) \ and sets up a mapping* *\.* **\** *can be \[--key-file, --keyfile-offset, --keyfile-size, --key-size,* *--readonly, --test-passphrase, --allow-discards --volume-key-file, --tries,* *--timeout, --verify-passphrase\].* ## OPTIONS - **--allow-discards** *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.* - **--batch-mode, -q** *Suppresses all confirmation questions. Use with care!* *If the --verify-passphrase option is not specified, this option also* *switches off the passphrase verification.* **--cipher, -c** *\* *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.* - **--debug or --debug-json** *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.* **--device-size** *size\[units\]* *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).* - **--disable-external-tokens** *Disable loading of plugins for external LUKS2 tokens.* - **--disable-keyring** *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.* - **--disable-locks** *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).* - **--disable-veracrypt** *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.* **--external-tokens-path** *absolute\_path* *Override system directory path where cryptsetup searches for external token* *handlers (or token plugins). It must be absolute path (starting with '/' character).* **--hash, -h** *\* *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.* **--header \** *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.* - **--help, -?** *Show help text and default parameters.* - **--iv-large-sectors** *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.* **--key-file, -d** *name* *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.* **--keyfile-offset** *value* *Skip value bytes at the beginning of the key file.* **--keyfile-size, -l** *value* *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.* **--key-size, -s** *bits* *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.* - **--key-slot, -S \<0-N\>** *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.* **--link-vk-to-keyring** *\::\* *Link volume key in a keyring with specified key name. The volume key is linked only* *if requested action is successfully finished (with --test-passphrase the verified* *volume key is linked in a keyring without taking further action).* *\ string has to contain existing kernel keyring* *description. The keyring name may be optionally prefixed with "%:" or "%keyring:" type descriptions.* *Or, the keyring may also be specified directly by numeric key id. Also special keyring notations* *starting with "@" may be used to select existing predefined kernel keyrings.* *The string "::" is delimiter used to separate keyring description and key description.* *\ part describes key type and key name of volume key linked in the keyring* *described in \. The type may be specified by adding "%\:" prefix in front of* *key name. If type is missing default user type is applied. If the key of same name and same type already exists (already linked in the keyring)* *it will get replaced in the process.* *See also* **KEY IDENTIFIERS** *section of* **keyctl***(1).* **--offset, -o \** *Start offset in the backend device in 512-byte sectors.* *This option is only relevant with plain or loopaes device types.* - **--perf-no\_read\_workqueue, --perf-no\_write\_workqueue** *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.* - **--perf-same\_cpu\_crypt** *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.* - **--perf-submit\_from\_crypt\_cpus** *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.* - **--persistent** *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.* - **--readonly, -r** *set up a read-only mapping.* - **--refresh** *Refreshes an active device with new set of parameters. See* **cryptsetup-refresh***(8) for more details.* **--sector-size** *bytes* *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.* - **--serialize-memory-hard-pbkdf** *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!* - **--shared** *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.* **--size, -b \** *Set the size of the device in sectors of 512 bytes.* *Usable only with plain device type.* **--skip, -p \** *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.* **--tcrypt-backup***,* **--tcrypt-hidden***,* **--tcrypt-system** *Specify which TrueCrypt on-disk* *header will be used to open the device. See TCRYPT section in* **cryptsetup***(8) for more info.* - **--test-passphrase** *Do not activate the device, just verify passphrase. The device mapping name is* *not mandatory if this option is used.* **--timeout, -t \** *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.* - **--token-id** *Specify what token to use and allow token PIN prompt to take precedence over interactive* *keyslot passphrase prompt. If omitted, all available tokens (not protected by PIN)* *will be checked before proceeding further with passphrase prompt.* - **--token-only** *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.* **--token-type** *type* *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.* - **--tries, -T** *How often the input of the passphrase shall be retried. The default is 3 tries.* - **--type \** *Specifies required device type, for more info read BASIC ACTIONS section in* **cryptsetup***(8).* - **--unbound** *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.* - **--usage** *Show short option help.* - **--veracrypt** *This option is ignored as VeraCrypt compatible mode is supported by* *default.* **--veracrypt-pim***,* **--veracrypt-query-pim** *Use a custom Personal Iteration Multiplier (PIM) for* *VeraCrypt device. See TCRYPT section in* **cryptsetup***(8) for more info.* - **--verify-passphrase, -y** *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.* - **--version, -V** *Show the program version.* **--volume-key-file, --master-key-file (OBSOLETE alias)** *Use a volume key stored in a file.* *This allows one to open luks and bitlk device types without giving a passphrase.*\ **--volume-key-keyring** *\* *Use a volume key stored in a keyring.* *This allows one to open luks and device types without giving a passphrase.* *The key and associated type has to be readable from userspace so that volume* *key digest may be verified in before activation.* *The \ uses keyctl-compatible syntax. This can either be a* *numeric key ID or a string name in the format %\:\. See* *also* **KEY IDENTIFIERS** *section of* **keyctl***(1). When no %\: prefix* *is specified we assume the key type is user (default type).* ## REPORTING BUGS *Report bugs at* **cryptsetup mailing list \** **or in** **Issues project section \.** **Please attach output of the failed command with --debug option added.** ## SEE ALSO **Cryptsetup FAQ \** **[cryptsetup(8)](/cryptsetup/8.md), [integritysetup(8)](/integritysetup/8.md) and [veritysetup(8)](/veritysetup/8.md)** ## CRYPTSETUP **Part of** **cryptsetup project \.**