cryptsetup-luksAddKey

title: cryptsetup-luksAddKey(8)

summary: add a new passphrase

text:
# cryptsetup-luksAddKey(8)

## NAME
cryptsetup-luksAddKey - add a new passphrase

## SYNOPSIS
cryptsetup luksAddKey [<options>] <device> [<key file with new key>]

## DESCRIPTION
Adds a keyslot protected by a new passphrase. An existing passphrase must be supplied interactively, via --key-file or LUKS2 token (plugin). Alternatively to existing passphrase user may pass directly volume key (via --volume-key-file). The new passphrase to be added can be specified interactively, read from the file given as the positional argument (also via --new-keyfile parameter) or via LUKS2 token.

NOTE: with --unbound option the action creates new unbound LUKS2 keyslot. The keyslot cannot be used for device activation. If you don’t pass new key via --volume-key-file option, new random key is generated. Existing passphrase for any active keyslot is not required.

NOTE: some parameters are effective only if used with LUKS2 format that supports per-keyslot parameters. For LUKS1, PBKDF type and hash algorithm is always the same for all keyslots.

<options> can be [--key-file, --keyfile-offset, --keyfile-size, --new-keyfile, --new-keyfile-offset, --new-keyfile-size, --key-slot, --new-key-slot, --volume-key-file, --force-password, --hash, --header, --disable-locks, --iter-time, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --unbound, --type, --keyslot-cipher, --keyslot-key-size, --key-size, --timeout, --token-id, --token-type, --token-only, --new-token-id, --verify-passphrase].

## OPTIONS
--type <device-type>

Specifies required device type, for more info read BASIC ACTIONS section in cryptsetup(8).

--hash, -h <hash-spec>

The specified hash is used for PBKDF2 and AF splitter.

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--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.

The passphrase supplied via --key-file is always the passphrase for existing keyslot requested by the command.

If you want to set a new passphrase via key file, you have to use a positional argument or parameter --new-keyfile.

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.

--new-keyfile name

Read the passphrase for a new keyslot 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.

This is alternative method to positional argument when adding new passphrase via kefile.

--new-keyfile-offset value

Skip value bytes at the start when adding a new passphrase from key file.

--new-keyfile-size value

Read a maximum of value bytes when adding a new passphrase from key file. The default is to read the whole file up to the compiled-in maximum length that can be queried with --help. Supplying more than the compiled in maximum aborts the operation. When --new-keyfile-offset is also given, reading starts after the offset.

--volume-key-file, --master-key-file (OBSOLETE alias)

Use a volume key stored in a file. This allows adding a new keyslot without having to know passphrase to existing one. It may be also used when no keyslot is active. WARNING: If you create your own volume key, you need to make sure to do it right. Otherwise, you can end up with a low-entropy or otherwise partially predictable volume key which will compromise security.

--key-slot, -S <0-N>

When used together with parameter --new-key-slot this option allows you to specify which key slot is selected for unlocking volume key. NOTE: This option is ignored if existing volume key gets unlocked via LUKS2 token (--token-id, --token-type or --token-only parameters) or when volume key is provided directly via --volume-key-file parameter.

NOTE: To maintain backward compatibility, without --new-key-slot parameter, this option allows you to specify which key slot is selected for the new key.

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.

--new-key-slot <0-N>

This option allows you to specify which key slot is selected for the new key. NOTE: When used this option affects --key-slot option.

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.

--key-size, -s bits

Provide volume key size in bits. The argument has to be a multiple of 8. This option is required when parameter --volume-key-file is used to provide current volume key. Also, it is used when new unbound keyslot is created by specifying --unbound parameter.

--pbkdf <PBKDF spec>

Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot. The PBKDF can be: pbkdf2 (for PBKDF2 according to RFC2898), argon2i for Argon2i or argon2id for Argon2id (see Argon2 <https://www.cryptolux.org/index.php/Argon2> for more info). For LUKS1, only PBKDF2 is accepted (no need to use this option). The default PBKDF for LUKS2 is set during compilation time and is available in cryptsetup --help output.

A PBKDF is used for increasing dictionary and brute-force attack cost for keyslot passwords. The parameters can be time, memory and parallel cost.

For PBKDF2, only time cost (number of iterations) applies. For Argon2i/id, there is also memory cost (memory required during the process of key derivation) and parallel cost (number of threads that run in parallel during the key derivation.

Note that increasing memory cost also increases time, so the final parameter values are measured by a benchmark. The benchmark tries to find iteration time (--iter-time) with required memory cost --pbkdf-memory. If it is not possible, the memory cost is decreased as well. The parallel cost --pbkdf-parallel is constant and is checked against available CPU cores.

You can see all PBKDF parameters for particular LUKS2 keyslot with cryptsetup-luksDump(8) command.

NOTE: If you do not want to use benchmark and want to specify all parameters directly, use --pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel. This will override the values without benchmarking. Note it can cause extremely long unlocking time. Use only in specific cases, for example, if you know that the formatted device will be used on some small embedded system.

MINIMAL AND MAXIMAL PBKDF COSTS: For PBKDF2, the minimum iteration count is 1000 and maximum is 4294967295 (maximum for 32bit unsigned integer). Memory and parallel costs are unused for PBKDF2. For Argon2i and Argon2id, minimum iteration count (CPU cost) is 4 and maximum is 4294967295 (maximum for 32bit unsigned integer). Minimum memory cost is 32 KiB and maximum is 4 GiB. (Limited by addressable memory on some CPU platforms.) If the memory cost parameter is benchmarked (not specified by a parameter) it is always in range from 64 MiB to 1 GiB. The parallel cost minimum is 1 and maximum 4 (if enough CPUs cores are available, otherwise it is decreased).

--iter-time, -i <number of milliseconds>

The number of milliseconds to spend with PBKDF passphrase processing. Specifying 0 as parameter selects the compiled-in default.

--pbkdf-memory <number>

Set the memory cost for PBKDF (for Argon2i/id the number represents kilobytes). Note that it is maximal value, PBKDF benchmark or available physical memory can decrease it. This option is not available for PBKDF2.

--pbkdf-parallel <number>

Set the parallel cost for PBKDF (number of threads, up to 4). Note that it is maximal value, it is decreased automatically if CPU online count is lower. This option is not available for PBKDF2.

--pbkdf-force-iterations <num>

Avoid PBKDF benchmark and set time cost (iterations) directly. It can be used for LUKS/LUKS2 device only. See --pbkdf option for more info.

--timeout, -t <number of seconds>

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.

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--force-password

Do not use password quality checking for new LUKS passwords. This option is ignored if cryptsetup is built without password quality checking support.

For more info about password quality check, see the manual page for pwquality.conf(5) and passwdqc.conf(5).

--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).

--token-id

Specify what token to use when unlocking existing keyslot to get volume key.

--new-token-id

Specify what token to use to get the passphrase for a new keyslot.

--token-only

Use only LUKS2 tokens to unlock existing volume key. NOTE: To create a new keyslot using passphrase provided by a token use --new-token-id parameter.

--token-type type

Specify what token type (all type tokens) to use when unlocking existing keyslot to get volume key.

--keyslot-cipher <cipher-spec>

This option can be used to set specific cipher encryption for the LUKS2 keyslot area.

--keyslot-key-size <bits>

This option can be used to set specific key size for the LUKS2 keyslot area.

--unbound

Creates new LUKS2 unbound keyslot.

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## EXAMPLES
NOTE: When not specified otherwise interactive passphrase prompt is always default method.

Add new keyslot using interactive passphrase prompt for both existing and new passphrase:

cryptsetup luksAddKey /dev/device

Add new keyslot using LUKS2 tokens to unlock existing keyslot with interactive passphrase prompt for new passphrase:

cryptsetup luksAddKey --token-only /dev/device

Add new keyslot using LUKS2 systemd-tpm2 tokens to unlock existing keyslot with interactive passphrase prompt for new passphrase (systemd-tpm2 token plugin must be available):

cryptsetup luksAddKey --token-type systemd-tpm2 /dev/device

Add new keyslot using interactive passphrase prompt for existing keyslot, reading new passphrase from key_file:

cryptsetup luksAddKey --new-keyfile key_file /dev/device or cryptsetup luksAddKey /dev/device key_file

Add new keyslot using volume stored in volume_key_file and LUKS2 token in slot 5 to get new keyslot passphrase (token in slot 5 must exist and respective token plugin must be available):

cryptsetup luksAddKey --volume-key-file volume_key_file --new-token-id 5 /dev/device

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksChangeKey

package: cryptsetup

title: cryptsetup-luksChangeKey(8)

summary: change an existing passphrase

text:
# cryptsetup-luksChangeKey(8)

## NAME
cryptsetup-luksChangeKey - change an existing passphrase

## SYNOPSIS
cryptsetup luksChangeKey [<options>] <device> [<new key file>]

## DESCRIPTION
Changes an existing passphrase. The passphrase to be changed must be supplied interactively or via --key-file. The new passphrase can be supplied interactively or in a file given as the positional argument.

If a key-slot is specified (via --key-slot), the passphrase for that key-slot must be given and the new passphrase will overwrite the specified key-slot. If no key-slot is specified and there is still a free key-slot, then the new passphrase will be put into a free key-slot before the key-slot containing the old passphrase is purged. If there is no free key-slot, then the key-slot with the old passphrase is overwritten directly.

WARNING: If a key-slot is overwritten, a media failure during this operation can cause the overwrite to fail after the old passphrase has been wiped and make the LUKS container inaccessible.

NOTE: some parameters are effective only if used with LUKS2 format that supports per-keyslot parameters. For LUKS1, PBKDF type and hash algorithm is always the same for all keyslots.

<options> can be [--key-file, --keyfile-offset, --keyfile-size, --new-keyfile-offset, --iter-time, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --new-keyfile-size, --key-slot, --force-password, --hash, --header, --disable-locks, --type, --keyslot-cipher, --keyslot-key-size, --timeout, --verify-passphrase].

## OPTIONS
--type <device-type>

Specifies required device type, for more info read BASIC ACTIONS section in cryptsetup(8).

--hash, -h <hash-spec>

The specified hash is used for PBKDF2 and AF splitter.

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--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.

The passphrase supplied via --key-file is always the passphrase for existing keyslot requested by the command.

If you want to set a new passphrase via key file, you have to use a positional argument or parameter --new-keyfile.

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.

--new-keyfile-offset value

Skip value bytes at the start when adding a new passphrase from key file.

--new-keyfile-size value

Read a maximum of value bytes when adding a new passphrase from key file. The default is to read the whole file up to the compiled-in maximum length that can be queried with --help. Supplying more than the compiled in maximum aborts the operation. When --new-keyfile-offset is also given, reading starts after the offset.

--key-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which key slot is selected for the new key. 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.

--pbkdf <PBKDF spec>

Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot. The PBKDF can be: pbkdf2 (for PBKDF2 according to RFC2898), argon2i for Argon2i or argon2id for Argon2id (see Argon2 <https://www.cryptolux.org/index.php/Argon2> for more info). For LUKS1, only PBKDF2 is accepted (no need to use this option). The default PBKDF for LUKS2 is set during compilation time and is available in cryptsetup --help output.

A PBKDF is used for increasing dictionary and brute-force attack cost for keyslot passwords. The parameters can be time, memory and parallel cost.

For PBKDF2, only time cost (number of iterations) applies. For Argon2i/id, there is also memory cost (memory required during the process of key derivation) and parallel cost (number of threads that run in parallel during the key derivation.

Note that increasing memory cost also increases time, so the final parameter values are measured by a benchmark. The benchmark tries to find iteration time (--iter-time) with required memory cost --pbkdf-memory. If it is not possible, the memory cost is decreased as well. The parallel cost --pbkdf-parallel is constant and is checked against available CPU cores.

You can see all PBKDF parameters for particular LUKS2 keyslot with cryptsetup-luksDump(8) command.

NOTE: If you do not want to use benchmark and want to specify all parameters directly, use --pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel. This will override the values without benchmarking. Note it can cause extremely long unlocking time. Use only in specific cases, for example, if you know that the formatted device will be used on some small embedded system.

MINIMAL AND MAXIMAL PBKDF COSTS: For PBKDF2, the minimum iteration count is 1000 and maximum is 4294967295 (maximum for 32bit unsigned integer). Memory and parallel costs are unused for PBKDF2. For Argon2i and Argon2id, minimum iteration count (CPU cost) is 4 and maximum is 4294967295 (maximum for 32bit unsigned integer). Minimum memory cost is 32 KiB and maximum is 4 GiB. (Limited by addressable memory on some CPU platforms.) If the memory cost parameter is benchmarked (not specified by a parameter) it is always in range from 64 MiB to 1 GiB. The parallel cost minimum is 1 and maximum 4 (if enough CPUs cores are available, otherwise it is decreased).

--iter-time, -i <number of milliseconds>

The number of milliseconds to spend with PBKDF passphrase processing. Specifying 0 as parameter selects the compiled-in default.

--pbkdf-memory <number>

Set the memory cost for PBKDF (for Argon2i/id the number represents kilobytes). Note that it is maximal value, PBKDF benchmark or available physical memory can decrease it. This option is not available for PBKDF2.

--pbkdf-parallel <number>

Set the parallel cost for PBKDF (number of threads, up to 4). Note that it is maximal value, it is decreased automatically if CPU online count is lower. This option is not available for PBKDF2.

--pbkdf-force-iterations <num>

Avoid PBKDF benchmark and set time cost (iterations) directly. It can be used for LUKS/LUKS2 device only. See --pbkdf option for more info.

--timeout, -t <number of seconds>

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.

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--force-password

Do not use password quality checking for new LUKS passwords. This option is ignored if cryptsetup is built without password quality checking support.

For more info about password quality check, see the manual page for pwquality.conf(5) and passwdqc.conf(5).

--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).

--keyslot-cipher <cipher-spec>

This option can be used to set specific cipher encryption for the LUKS2 keyslot area.

--keyslot-key-size <bits>

This option can be used to set specific key size for the LUKS2 keyslot area.

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksConvertKey

title: cryptsetup-luksConvertKey(8)

text:
# cryptsetup-luksConvertKey(8)

## NAME
cryptsetup-luksConvertKey - converts an existing LUKS2 keyslot to new PBKDF parameters

## SYNOPSIS
cryptsetup luksConvertKey [<options>] <device>

## DESCRIPTION
Converts an existing LUKS2 keyslot to new PBKDF parameters. The passphrase for keyslot to be converted must be supplied interactively or via --key-file. If no --pbkdf parameters are specified LUKS2 default PBKDF values will apply.

If a keyslot is specified (via --key-slot), the passphrase for that keyslot must be given. If no keyslot is specified and there is still a free keyslot, then the new parameters will be put into a free keyslot before the keyslot containing the old parameters is purged. If there is no free keyslot, then the keyslot with the old parameters is overwritten directly.

WARNING: If a keyslot is overwritten, a media failure during this operation can cause the overwrite to fail after the old parameters have been wiped and make the LUKS container inaccessible.

<options> can be [--key-file, --keyfile-offset, --keyfile-size, --key-slot, --hash, --header, --disable-locks, --iter-time, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --keyslot-cipher, --keyslot-key-size, --timeout, --verify-passphrase].

## OPTIONS
--hash, -h <hash-spec>

The specified hash is used for PBKDF2 and AF splitter.

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--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.

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.

--new-keyfile-offset value

Skip value bytes at the start when adding a new passphrase from key file.

--new-keyfile-size value

Read a maximum of value bytes when adding a new passphrase from key file. The default is to read the whole file up to the compiled-in maximum length that can be queried with --help. Supplying more than the compiled in maximum aborts the operation. When --new-keyfile-offset is also given, reading starts after the offset.

--key-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which key slot is selected for the new key. 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.

--pbkdf <PBKDF spec>

Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot. The PBKDF can be: pbkdf2 (for PBKDF2 according to RFC2898), argon2i for Argon2i or argon2id for Argon2id (see Argon2 <https://www.cryptolux.org/index.php/Argon2> for more info). For LUKS1, only PBKDF2 is accepted (no need to use this option). The default PBKDF for LUKS2 is set during compilation time and is available in cryptsetup --help output.

A PBKDF is used for increasing dictionary and brute-force attack cost for keyslot passwords. The parameters can be time, memory and parallel cost.

For PBKDF2, only time cost (number of iterations) applies. For Argon2i/id, there is also memory cost (memory required during the process of key derivation) and parallel cost (number of threads that run in parallel during the key derivation.

Note that increasing memory cost also increases time, so the final parameter values are measured by a benchmark. The benchmark tries to find iteration time (--iter-time) with required memory cost --pbkdf-memory. If it is not possible, the memory cost is decreased as well. The parallel cost --pbkdf-parallel is constant and is checked against available CPU cores.

You can see all PBKDF parameters for particular LUKS2 keyslot with cryptsetup-luksDump(8) command.

NOTE: If you do not want to use benchmark and want to specify all parameters directly, use --pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel. This will override the values without benchmarking. Note it can cause extremely long unlocking time. Use only in specific cases, for example, if you know that the formatted device will be used on some small embedded system.

MINIMAL AND MAXIMAL PBKDF COSTS: For PBKDF2, the minimum iteration count is 1000 and maximum is 4294967295 (maximum for 32bit unsigned integer). Memory and parallel costs are unused for PBKDF2. For Argon2i and Argon2id, minimum iteration count (CPU cost) is 4 and maximum is 4294967295 (maximum for 32bit unsigned integer). Minimum memory cost is 32 KiB and maximum is 4 GiB. (Limited by addressable memory on some CPU platforms.) If the memory cost parameter is benchmarked (not specified by a parameter) it is always in range from 64 MiB to 1 GiB. The parallel cost minimum is 1 and maximum 4 (if enough CPUs cores are available, otherwise it is decreased).

--iter-time, -i <number of milliseconds>

The number of milliseconds to spend with PBKDF passphrase processing. Specifying 0 as parameter selects the compiled-in default.

--pbkdf-memory <number>

Set the memory cost for PBKDF (for Argon2i/id the number represents kilobytes). Note that it is maximal value, PBKDF benchmark or available physical memory can decrease it. This option is not available for PBKDF2.

--pbkdf-parallel <number>

Set the parallel cost for PBKDF (number of threads, up to 4). Note that it is maximal value, it is decreased automatically if CPU online count is lower. This option is not available for PBKDF2.

--pbkdf-force-iterations <num>

Avoid PBKDF benchmark and set time cost (iterations) directly. It can be used for LUKS/LUKS2 device only. See --pbkdf option for more info.

--timeout, -t <number of seconds>

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.

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--force-password

Do not use password quality checking for new LUKS passwords. This option is ignored if cryptsetup is built without password quality checking support.

For more info about password quality check, see the manual page for pwquality.conf(5) and passwdqc.conf(5).

--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).

--keyslot-cipher <cipher-spec>

This option can be used to set specific cipher encryption for the LUKS2 keyslot area.

--keyslot-key-size <bits>

This option can be used to set specific key size for the LUKS2 keyslot area.

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksDump

title: cryptsetup-luksDump(8)

text:
# cryptsetup-luksDump(8)

## NAME
cryptsetup-luksDump - dump the header information of a LUKS device

## SYNOPSIS
cryptsetup luksDump [<options>] <device>

## DESCRIPTION
Dump the header information of a LUKS device.

If the --dump-volume-key option is used, the LUKS device volume key is dumped instead of the keyslot info. Together with the --volume-key-file option, volume key is dumped to a file instead of standard output. Beware that the volume key cannot be changed without reencryption and can be used to decrypt the data stored in the LUKS container without a passphrase and even without the LUKS header. This means that if the volume key is compromised, the whole device has to be erased or reencrypted to prevent further access. Use this option carefully.

To dump the volume key, a passphrase has to be supplied, either interactively or via --key-file.

To dump unbound key (LUKS2 format only), --unbound parameter, specific --key-slot id and proper passphrase has to be supplied, either interactively or via --key-file. Optional --volume-key-file parameter enables unbound keyslot dump to a file.

To dump LUKS2 JSON metadata (without basic header information like UUID) use --dump-json-metadata option.

<options> can be [--dump-volume-key, --dump-json-metadata, --key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --volume-key-file, --type, --unbound, --key-slot, --timeout].

WARNING: If --dump-volume-key is used with --key-file and the argument to --key-file is '-', no validation question will be asked and no warning given.

## OPTIONS
--type <device-type>

Specifies required device type, for more info read BASIC ACTIONS section in cryptsetup(8).

--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.

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.

--volume-key-file, --master-key-file (OBSOLETE alias)

Use a volume key stored in a file. The volume key is stored in a file instead of being printed out to standard output.

--dump-json-metadata

For luksDump (LUKS2 only) this option prints content of LUKS2 header JSON metadata area.

--dump-volume-key, --dump-master-key (OBSOLETE alias)

Print the volume key in the displayed information. Use with care, as the volume key can be used to bypass the passphrases, see also option --volume-key-file.

--key-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which key slot is selected for the new key. 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.

--timeout, -t <number of seconds>

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.

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--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).

--unbound

Dumps existing LUKS2 unbound keyslot.

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksFormat

title: cryptsetup-luksFormat(8)

text:
# cryptsetup-luksFormat(8)

## NAME
cryptsetup-luksFormat - initialize a LUKS partition and set the initial passphrase

## SYNOPSIS
cryptsetup luksFormat [<options>] <device> [<key file>]

## DESCRIPTION
Initializes a LUKS partition and sets the initial passphrase (for key-slot 0), either via prompting or via <key file>. Note that if the second argument is present, then the passphrase is taken from the file given there, without the need to use the --key-file option. Also note that for both forms of reading the passphrase from a file you can give '-' as file name, which results in the passphrase being read from stdin and the safety-question being skipped.

You cannot call luksFormat on a device or filesystem that is mapped or in use, e.g., mounted filesystem, used in LVM, active RAID member, etc. The device or filesystem has to be un-mounted in order to call luksFormat.

To use specific version of LUKS format, use --type luks1 or type luks2.

<options> can be [--hash, --cipher, --verify-passphrase, --key-size, --key-slot, --key-file (takes precedence over optional second argument), --keyfile-offset, --keyfile-size, --use-random, --use-urandom, --uuid, --volume-key-file, --iter-time, --header, --pbkdf-force-iterations, --force-password, --disable-locks, --timeout, --type, --offset, --align-payload (deprecated)].

For LUKS2, additional <options> can be [--integrity, --integrity-no-wipe, --sector-size, --label, --subsystem, --pbkdf, --pbkdf-memory, --pbkdf-parallel, --disable-locks, --disable-keyring, --luks2-metadata-size, --luks2-keyslots-size, --keyslot-cipher, --keyslot-key-size, --integrity-legacy-padding].

WARNING: Doing a luksFormat on an existing LUKS container will make all data in the old container permanently irretrievable unless you have a header backup.

## OPTIONS
--type <device-type>

Specifies required device type, for more info read BASIC ACTIONS section in cryptsetup(8).

--hash, -h <hash-spec>

Specifies the hash used in the LUKS key setup scheme and volume key digest. The specified hash is used for PBKDF2 and AF splitter. The hash algorithm must provide at least 160 bits of output. Do not use a non-crypto hash like xxhash as this breaks security. Use cryptsetup --help to show the defaults.

--cipher, -c <cipher-spec>

Set the cipher specification string. 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.

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--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.

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.

--volume-key-file, --master-key-file (OBSOLETE alias)

Use a volume key stored in a file. WARNING: If you create your own volume key, you need to make sure to do it right. Otherwise, you can end up with a low-entropy or otherwise partially predictable volume key which will compromise security.

--use-random, --use-urandom

For luksFormat these options define which kernel random number generator will be used to create the volume key (which is a long-term key). See NOTES ON RANDOM NUMBER GENERATORS in cryptsetup(8) for more information. Use cryptsetup --help to show the compiled-in default random number generator.

WARNING: In a low-entropy situation (e.g. in an embedded system) and older kernels, both selections are problematic. Using /dev/urandom can lead to weak keys. Using /dev/random can block a long time, potentially forever, if not enough entropy can be harvested by the kernel.

--key-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which key slot is selected for the new key. 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.

--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 open --type plain or luksFormat. All other LUKS actions will use the key-size specified in the LUKS header. Use cryptsetup --help to show the compiled-in defaults.

--offset, -o <number of 512 byte sectors>

Start offset in the backend device in 512-byte sectors. The --offset option sets the data offset (payload) of data device and must be aligned to 4096-byte sectors (must be multiple of 8). This option cannot be combined with --align-payload option.

--pbkdf <PBKDF spec>

Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot. The PBKDF can be: pbkdf2 (for PBKDF2 according to RFC2898), argon2i for Argon2i or argon2id for Argon2id (see Argon2 <https://www.cryptolux.org/index.php/Argon2> for more info). For LUKS1, only PBKDF2 is accepted (no need to use this option). The default PBKDF for LUKS2 is set during compilation time and is available in cryptsetup --help output.

A PBKDF is used for increasing dictionary and brute-force attack cost for keyslot passwords. The parameters can be time, memory and parallel cost.

For PBKDF2, only time cost (number of iterations) applies. For Argon2i/id, there is also memory cost (memory required during the process of key derivation) and parallel cost (number of threads that run in parallel during the key derivation.

Note that increasing memory cost also increases time, so the final parameter values are measured by a benchmark. The benchmark tries to find iteration time (--iter-time) with required memory cost --pbkdf-memory. If it is not possible, the memory cost is decreased as well. The parallel cost --pbkdf-parallel is constant and is checked against available CPU cores.

You can see all PBKDF parameters for particular LUKS2 keyslot with cryptsetup-luksDump(8) command.

NOTE: If you do not want to use benchmark and want to specify all parameters directly, use --pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel. This will override the values without benchmarking. Note it can cause extremely long unlocking time. Use only in specific cases, for example, if you know that the formatted device will be used on some small embedded system.

MINIMAL AND MAXIMAL PBKDF COSTS: For PBKDF2, the minimum iteration count is 1000 and maximum is 4294967295 (maximum for 32bit unsigned integer). Memory and parallel costs are unused for PBKDF2. For Argon2i and Argon2id, minimum iteration count (CPU cost) is 4 and maximum is 4294967295 (maximum for 32bit unsigned integer). Minimum memory cost is 32 KiB and maximum is 4 GiB. (Limited by addressable memory on some CPU platforms.) If the memory cost parameter is benchmarked (not specified by a parameter) it is always in range from 64 MiB to 1 GiB. The parallel cost minimum is 1 and maximum 4 (if enough CPUs cores are available, otherwise it is decreased).

--iter-time, -i <number of milliseconds>

The number of milliseconds to spend with PBKDF passphrase processing. Specifying 0 as parameter selects the compiled-in default.

--pbkdf-memory <number>

Set the memory cost for PBKDF (for Argon2i/id the number represents kilobytes). Note that it is maximal value, PBKDF benchmark or available physical memory can decrease it. This option is not available for PBKDF2.

--pbkdf-parallel <number>

Set the parallel cost for PBKDF (number of threads, up to 4). Note that it is maximal value, it is decreased automatically if CPU online count is lower. This option is not available for PBKDF2.

--pbkdf-force-iterations <num>

Avoid PBKDF benchmark and set time cost (iterations) directly. It can be used for LUKS/LUKS2 device only. See --pbkdf option for more info.

--progress-frequency seconds

Print separate line every seconds with wipe progress.

--progress-json

Prints progress data in JSON format suitable mostly for machine processing. It prints separate line every half second (or based on --progress-frequency value). The JSON output looks as follows during progress (except it’s compact single line):

```
{

  "device":"/dev/sda"       // backing device or file

  "device_bytes":"8192",    // bytes of I/O so far

  "device_size":"44040192", // total bytes of I/O to go

  "speed":"126877696",      // calculated speed in bytes per second (based on progress so far)

  "eta_ms":"2520012"        // estimated time to finish an operation in milliseconds

  "time_ms":"5561235"       // total time spent in IO operation in milliseconds
}
```

Note on numbers in JSON output: Due to JSON parsers limitations all numbers are represented in a string format due to need of full 64bit unsigned integers.

--timeout, -t <number of seconds>

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.

--align-payload <number of 512 byte sectors>

Align payload at a boundary of value 512-byte sectors. If not specified, cryptsetup tries to use the topology info provided by the kernel for the underlying device to get the optimal alignment. If not available (or the calculated value is a multiple of the default) data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte sectors).

For a detached LUKS header, this option specifies the offset on the data device. See also the --header option.

WARNING: This option is DEPRECATED and has often unexpected impact to the data offset and keyslot area size (for LUKS2) due to the complex rounding. For fixed data device offset use --offset option instead.

--uuid <UUID>

Use the provided UUID for the luksFormat command instead of generating a new one. Changes the existing UUID when used with the luksUUID command. The UUID must be provided in the standard UUID format, e.g. 12345678-1234-1234-1234-123456789abc.

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. With a file name as the argument to --header, the file will be automatically created if it does not exist. See the cryptsetup FAQ for header size calculation.

The --align-payload option is taken as absolute sector alignment on ciphertext device and can be zero.

--force-password

Do not use password quality checking for new LUKS passwords. This option is ignored if cryptsetup is built without password quality checking support.

For more info about password quality check, see the manual page for pwquality.conf(5) and passwdqc.conf(5).

--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-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.

--sector-size bytes

Set sector size for use with disk encryption. It must be power of two and in range 512 - 4096 bytes. This option is available only with LUKS2 format. For LUKS2 devices it’s established based on parameters provided by underlying data device. For native 4K block devices it’s 4096 bytes. For 4K/512e (4K physical sector size with 512 bytes emulation) it’s 4096 bytes. For drives reporting only 512 bytes block size it remains 512 bytes. If data device is regular file put in filesystem it’s 4096 bytes.

Note that if sector size is higher than underlying device hardware sector and there is not integrity protection that uses data journal, using this option can increase risk on incomplete sector writes during a power fail.

If used together with --integrity option and dm-integrity journal, the atomicity of writes is guaranteed in all cases (but it cost write performance - data has to be written twice).

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.

--label <LABEL> --subsystem <SUBSYSTEM>

Set label and subsystem description for LUKS2 device. The label and subsystem are optional fields and can be later used in udev scripts for triggering user actions once the device marked by these labels is detected.

--integrity <integrity algorithm>

Specify integrity algorithm to be used for authenticated disk encryption in LUKS2. WARNING: This extension is EXPERIMENTAL and requires dm-integrity kernel target (available since kernel version 4.12). For native AEAD modes, also enable "User-space interface for AEAD cipher algorithms" in "Cryptographic API" section (CONFIG_CRYPTO_USER_API_AEAD .config option).

For more info, see AUTHENTICATED DISK ENCRYPTION section in cryptsetup(8).

--integrity-legacy-padding

Use inefficient legacy padding. WARNING: Do not use this option until you need compatibility with specific old kernel.

--luks2-metadata-size <size>

This option can be used to enlarge the LUKS2 metadata (JSON) area. The size includes 4096 bytes for binary metadata (usable JSON area is smaller of the binary area). According to LUKS2 specification, only these values are valid: 16, 32, 64, 128, 256, 512, 1024, 2048 and 4096 kB The <size> can be specified with unit suffix (for example 128k).

--luks2-keyslots-size <size>

This option can be used to set specific size of the LUKS2 binary keyslot area (key material is encrypted there). The value must be aligned to multiple of 4096 bytes with maximum size 128MB. The <size> can be specified with unit suffix (for example 128k).

--keyslot-cipher <cipher-spec>

This option can be used to set specific cipher encryption for the LUKS2 keyslot area.

--keyslot-key-size <bits>

This option can be used to set specific key size for the LUKS2 keyslot area.

--integrity-no-wipe

Skip wiping of device authentication (integrity) tags. If you skip this step, sectors will report invalid integrity tag until an application write to the sector. NOTE: Even some writes to the device can fail if the write is not aligned to page size and page-cache initiates read of a sector with invalid integrity tag.

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksHeaderBackup

title: cryptsetup-luksHeaderBackup(8)

text:
# cryptsetup-luksHeaderBackup(8)

## NAME
cryptsetup-luksHeaderBackup - store a binary backup of the LUKS header and keyslot area

## SYNOPSIS
cryptsetup luksHeaderBackup --header-backup-file <file> [<options>] <device>

## DESCRIPTION
Stores a binary backup of the LUKS header and keyslot area.

NOTE: Using '-' as filename writes the header backup to a file named '-'.

<options> can be [--header, --header-backup-file, --disable-locks].

WARNING: This backup file and a passphrase valid at the time of backup allows decryption of the LUKS data area, even if the passphrase was later changed or removed from the LUKS device. Also note that with a header backup you lose the ability to securely wipe the LUKS device by just overwriting the header and key-slots. You either need to securely erase all header backups in addition or overwrite the encrypted data area as well. The second option is less secure, as some sectors can survive, e.g., due to defect management.

## OPTIONS
--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--header-backup-file <file>

Specify file with header backup file.

--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).

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksHeaderRestore

title: cryptsetup-luksHeaderRestore(8)

text:
# cryptsetup-luksHeaderRestore(8)

## NAME
cryptsetup-luksHeaderRestore - restore a binary backup of the LUKS header and keyslot area

## SYNOPSIS
cryptsetup luksHeaderRestore --header-backup-file <file> [<options>] <device>

## DESCRIPTION
Restores a binary backup of the LUKS header and keyslot area from the specified file.

NOTE: Using '-' as filename reads the header backup from a file named '-'.

<options> can be [--header, --header-backup-file, --disable-locks].

WARNING: Header and keyslots will be replaced, only the passphrases from the backup will work afterward.

This command requires that the volume key size and data offset of the LUKS header already on the device and of the header backup match. Alternatively, if there is no LUKS header on the device, the backup will also be written to it.

## OPTIONS
--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--header-backup-file <file>

Specify file with header backup file.

--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).

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksKillSlot

title: cryptsetup-luksKillSlot(8)

summary: wipe a key\-slot from the LUKS device

text:
# cryptsetup-luksKillSlot(8)

## NAME
cryptsetup-luksKillSlot - wipe a key-slot from the LUKS device

## SYNOPSIS
cryptsetup luksKillSlot [<options>] <device> <key slot number>

## DESCRIPTION
Wipe the key-slot number <key slot> from the LUKS device. Except running in batch-mode (-q) a remaining passphrase must be supplied, either interactively or via --key-file. This command can remove the last remaining key-slot, but requires an interactive confirmation when doing so. Removing the last passphrase makes a LUKS container permanently inaccessible.

<options> can be [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type, --verify-passphrase, --timeout].

WARNING: If you read the passphrase from stdin (without further argument or with '-' as an argument to --key-file), batch-mode (-q) will be implicitly switched on and no warning will be given when you remove the last remaining passphrase from a LUKS container. Removing the last passphrase makes the LUKS container permanently inaccessible.

NOTE: If there is no passphrase provided (on stdin or through --key-file argument) and batch-mode (-q) is active, the key-slot is removed without any other warning.

## OPTIONS
--type <device-type>

Specifies required device type, for more info read BASIC ACTIONS section in cryptsetup(8).

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--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.

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.

--timeout, -t <number of seconds>

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.

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--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).

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksRemoveKey

title: cryptsetup-luksRemoveKey(8)

text:
# cryptsetup-luksRemoveKey(8)

## NAME
cryptsetup-luksRemoveKey - remove the supplied passphrase from the LUKS device

## SYNOPSIS
cryptsetup luksRemoveKey [<options>] <device> [<key file with passphrase to be removed>]

## DESCRIPTION
Removes the supplied passphrase from the LUKS device. The passphrase to be removed can be specified interactively, as the positional argument or via --key-file.

<options> can be [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type, --timeout, --verify-passphrase].

WARNING: If you read the passphrase from stdin (without further argument or with '-' as an argument to --key-file), batch-mode (-q) will be implicitly switched on and no warning will be given when you remove the last remaining passphrase from a LUKS container. Removing the last passphrase makes the LUKS container permanently inaccessible.

## OPTIONS
--type <device-type>

Specifies required device type, for more info read BASIC ACTIONS section in cryptsetup(8).

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--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.

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.

--timeout, -t <number of seconds>

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.

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--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).

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksResume

title: cryptsetup-luksResume(8)

text:
# cryptsetup-luksResume(8)

## NAME
cryptsetup-luksResume - resume a suspended device and reinstate the key

## SYNOPSIS
cryptsetup luksResume [<options>] <name>

## DESCRIPTION
Resumes a suspended device and reinstates the encryption key. Prompts interactively for a passphrase if no token is usable (LUKS2 only) or --key-file is not given.

<options> can be [--key-file, --keyfile-size, --keyfile-offset, --key-slot, --header, --disable-keyring, --disable-locks, --token-id, --token-only, --token-type, --disable-external-tokens, --type, --tries, --timeout, --verify-passphrase].

## OPTIONS
--type <device-type>

Specifies required device type, for more info read BASIC ACTIONS section in cryptsetup(8).

--verify-passphrase, -y

When interactively asking for a passphrase, ask for it twice and complain if both inputs do not match. Ignored on input from file or stdin.

--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.

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-slot, -S <0-N>

For LUKS operations that add key material, this option allows you to specify which key slot is selected for the new key. 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.

--timeout, -t <number of seconds>

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.

--tries, -T

How often the input of the passphrase shall be retried. The default is 3 tries.

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--disable-external-tokens

Disable loading of plugins for external LUKS2 tokens.

--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-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.

--token-id

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.

--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.

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksSuspend

title: cryptsetup-luksSuspend(8)

text:
# cryptsetup-luksSuspend(8)

## NAME
cryptsetup-luksSuspend - suspends an active device and wipes the key

## SYNOPSIS
cryptsetup luksSuspend [<options>] <name>

## DESCRIPTION
Suspends an active device (all IO operations will block and accesses to the device will wait indefinitely) and wipes the encryption key from kernel memory. Needs kernel 2.6.19 or later.

After this operation, you have to use luksResume to reinstate the encryption key and unblock the device or close to remove the mapped device.

<options> can be [--header, --disable-locks].

WARNING: Never suspend the device on which the cryptsetup binary resides.

## OPTIONS
--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--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).

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-luksUUID

title: cryptsetup-luksUUID(8)

summary: print or set the UUID of a LUKS device

text:
# cryptsetup-luksUUID(8)

## NAME
cryptsetup-luksUUID - print or set the UUID of a LUKS device

## SYNOPSIS
cryptsetup luksUUID [<options>] <device>

## DESCRIPTION
Print the UUID of a LUKS device.

Set new UUID if --uuid option is specified.

<options> can be [--header, --uuid, --type, --disable-locks].

## OPTIONS
--type <device-type>

Specifies required device type, for more info read BASIC ACTIONS section in cryptsetup(8).

--uuid <UUID>

Use the provided UUID for the luksFormat command instead of generating a new one. Changes the existing UUID when used with the luksUUID command. The UUID must be provided in the standard UUID format, e.g. 12345678-1234-1234-1234-123456789abc.

--header <device or file storing the LUKS header>

Use a detached (separated) metadata device or file where the LUKS header is stored. This option allows one to store ciphertext and LUKS header on different devices. For commands that change the LUKS header (e.g. luksAddKey), specify the device or file with the LUKS header directly as the LUKS device.

--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).

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.


cryptsetup-open

title: cryptsetup-open(8)

text:
# cryptsetup-open(8)

## 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>

plainOpen <device> <name> (old syntax)

create <name> <device> (OBSOLETE syntax)

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

<options> 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 /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 <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 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.

<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].

### 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 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).

<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 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 <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].

### 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].

## OPTIONS
--type <device-type>

Specifies required device type, for more info read BASIC ACTIONS section in cryptsetup(8).

--hash, -h <hash-spec>

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.

--cipher, -c <cipher-spec>

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.

--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.

--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.

--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.

--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.

--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.

--size, -b <number of 512 byte sectors>

Set the size of the device in sectors of 512 bytes. Usable only with plain device type.

--offset, -o <number of 512 byte sectors>

Start offset in the backend device in 512-byte sectors. This option is only relevant with plain or loopaes device types.

--skip, -p <number of 512 byte sectors>

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.

--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).

--readonly, -r

set up a read-only mapping.

--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.

--timeout, -t <number of seconds>

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.

--tries, -T

How often the input of the passphrase shall be retried. The default is 3 tries.

--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.

--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.

--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.

--test-passphrase

Do not activate the device, just verify passphrase. The device mapping name is not mandatory if this option is used.

--header <device or file storing the LUKS 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.

--disable-external-tokens

Disable loading of plugins for external LUKS2 tokens.

--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-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.

--token-id

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.

--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.

--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.

--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.

--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.

--refresh

Refreshes an active device with new set of parameters. See cryptsetup-refresh(8) for more details.

--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.

--tcrypt-hidden, --tcrypt-system, --tcrypt-backup

Specify which TrueCrypt on-disk header will be used to open the device. See TCRYPT section in cryptsetup(8) for more info.

--veracrypt

This option is ignored as VeraCrypt compatible mode is supported by default.

--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.

--veracrypt-pim, --veracrypt-query-pim

Use a custom Personal Iteration Multiplier (PIM) for VeraCrypt device. See TCRYPT section in cryptsetup(8) for more info.

--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!

--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.

--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.

--version, -V

Show the program version.

--usage

Show short option help.

--help, -?

Show help text and default parameters.

## REPORTING BUGS
Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or in Issues project section <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.

Please attach output of the failed command with --debug option added.

## SEE ALSO
Cryptsetup FAQ <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>

cryptsetup(8), integritysetup(8) and veritysetup(8)

## CRYPTSETUP
Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.