|
|
|
|
@@ -64,10 +64,10 @@ Set the cipher specification string for the data segment only.
|
|
|
|
|
*LUKS1*:
|
|
|
|
|
Set the cipher specification string for the data segment and keyslots.
|
|
|
|
|
+
|
|
|
|
|
*NOTE*: In encrypt mode, if cipher specification is omitted, the default cipher is applied.
|
|
|
|
|
In reencrypt mode, if no new cipher specification is requested, the existing cipher will remain in use.
|
|
|
|
|
Unless the existing cipher was "cipher_null".
|
|
|
|
|
In that case, the default cipher would be applied as in encrypt mode.
|
|
|
|
|
The default cipher is applied if the cipher specification is omitted in encrypt mode.
|
|
|
|
|
+
|
|
|
|
|
In reencrypt mode, if no new cipher specification is requested, the existing cipher will remain.
|
|
|
|
|
The only exception is if the cipher is "cipher_null", then the default cipher is used.
|
|
|
|
|
endif::[]
|
|
|
|
|
ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
|
|
|
|
|
+
|
|
|
|
|
@@ -117,7 +117,6 @@ It means that only the specified area (from the start of the device to the speci
|
|
|
|
|
*LUKS2*:
|
|
|
|
|
When used together with --reduce-device-size, only the initial _size_ value (--device-size parameter) of data is shifted backwards while being encrypted.
|
|
|
|
|
+
|
|
|
|
|
*NOTE*:
|
|
|
|
|
The sum of --device-size and --reduce-device-size values must not exceed the real device size.
|
|
|
|
|
+
|
|
|
|
|
*WARNING:* This is a destructive operation.
|
|
|
|
|
@@ -151,7 +150,7 @@ Disable lock protection for metadata on disk.
|
|
|
|
|
This option is valid only for LUKS2 and is ignored for other formats.
|
|
|
|
|
+
|
|
|
|
|
ifdef::ACTION_REENCRYPT[]
|
|
|
|
|
*NOTE:* With locking disabled, LUKS2 images in files can be fully (re)encrypted offline without the need for superuser privileges provided that the used block ciphers are available in the crypto backend.
|
|
|
|
|
With locking disabled, LUKS2 images in files can be fully (re)encrypted offline without the need for superuser privileges provided that the used block ciphers are available in the crypto backend.
|
|
|
|
|
+
|
|
|
|
|
endif::[]
|
|
|
|
|
*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).
|
|
|
|
|
@@ -191,7 +190,7 @@ ifdef::ACTION_REENCRYPT[]
|
|
|
|
|
Enforce initialization of reencryption operation with additional --volume-key-file, --new-volume-key-file, --volume-key-keyring or --new-volume-key-keyring parameters.
|
|
|
|
|
It would result in the deletion of all remaining LUKS2 keyslots containing the volume key.
|
|
|
|
|
+
|
|
|
|
|
*NOTE:* LUKS2 keyslot with new volume key may be added after the reencryption operation is finished.
|
|
|
|
|
LUKS2 keyslot with the new volume key may be added after the reencryption operation is finished.
|
|
|
|
|
See *cryptsetup-luksAddKey*(8) command.
|
|
|
|
|
+
|
|
|
|
|
*WARNING:* Use with extreme caution!
|
|
|
|
|
@@ -236,7 +235,7 @@ ifdef::ACTION_REENCRYPT[]
|
|
|
|
|
*LUKS1:*
|
|
|
|
|
Specifies the hash used in the LUKS1 key setup scheme and volume key digest.
|
|
|
|
|
+
|
|
|
|
|
*NOTE*: If this parameter is not specified, the default hash algorithm is always used for a new LUKS1 device header.
|
|
|
|
|
If this parameter is not specified, the default hash algorithm is always used for a new LUKS1 device header.
|
|
|
|
|
+
|
|
|
|
|
*LUKS2:* Ignored unless new keyslot pbkdf algorithm is set to PBKDF2 (see --pbkdf).
|
|
|
|
|
endif::[]
|
|
|
|
|
@@ -325,7 +324,7 @@ After providing the correct PSID via interactive prompt or via --key-file parame
|
|
|
|
|
PSID is usually printed on the OPAL drive label (either directly or as a QR code).
|
|
|
|
|
PSID must be entered without any dashes, spaces or underscores.
|
|
|
|
|
+
|
|
|
|
|
*NOTE*: PSID should be treated as sensitive information as it allows anyone with remote access to the OPAL drive to destroy data even if the device is locked.
|
|
|
|
|
PSID should be treated as sensitive information as it allows anyone with remote access to the OPAL drive to destroy data even if the device is locked.
|
|
|
|
|
Be sure you do not leak PSID through transparent packaging during transport or images of the drive posted online.
|
|
|
|
|
endif::[]
|
|
|
|
|
|
|
|
|
|
@@ -335,7 +334,7 @@ Format LUKS2 device with HW based encryption configured on SED OPAL locking rang
|
|
|
|
|
LUKS2 format only manages the locking range unlock key.
|
|
|
|
|
This option enables HW-based data encryption managed by the SED OPAL drive only.
|
|
|
|
|
+
|
|
|
|
|
*NOTE*: Please note that with OPAL-only (--hw-opal-only) encryption, the configured OPAL administrator PIN (passphrase) allows unlocking all configured locking ranges without LUKS keyslot decryption (without knowledge of LUKS passphrase).
|
|
|
|
|
Please note that with OPAL-only (--hw-opal-only) encryption, the configured OPAL administrator PIN (passphrase) allows unlocking all configured locking ranges without LUKS keyslot decryption (without knowledge of LUKS passphrase).
|
|
|
|
|
Because of many observed problems with compatibility, cryptsetup currently DOES NOT use OPAL single-user mode, which would allow such decoupling of OPAL admin PIN access.
|
|
|
|
|
endif::[]
|
|
|
|
|
|
|
|
|
|
@@ -393,7 +392,9 @@ ifdef::ACTION_LUKSFORMAT[]
|
|
|
|
|
Skip wiping of device authentication (integrity) tags.
|
|
|
|
|
If you skip this step, sectors will report an invalid integrity tag until an application writes to the sector.
|
|
|
|
|
+
|
|
|
|
|
*NOTE:* Even some writes to the device can fail if the write is not aligned to the page size and the page cache initiates a read of a sector with an invalid integrity tag.
|
|
|
|
|
Skipping this step could also cause write failures due to IO operation alignments.
|
|
|
|
|
For example, kernel page cache can request a read of a full page that fails due to an uninitialized integrity tag.
|
|
|
|
|
It is usually a bug in the application that tries to read data that was not written before.
|
|
|
|
|
endif::[]
|
|
|
|
|
|
|
|
|
|
ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[]
|
|
|
|
|
@@ -412,7 +413,7 @@ ifdef::ACTION_OPEN[]
|
|
|
|
|
Count Initialization Vector (IV) in larger sector size (if set) instead of 512-byte sectors.
|
|
|
|
|
This option can be used only with the _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.
|
|
|
|
|
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.
|
|
|
|
|
endif::[]
|
|
|
|
|
|
|
|
|
|
ifdef::ACTION_TOKEN[]
|
|
|
|
|
@@ -455,7 +456,7 @@ endif::[]
|
|
|
|
|
+
|
|
|
|
|
endif::[]
|
|
|
|
|
ifdef::ACTION_OPEN[]
|
|
|
|
|
*NOTE:* With _plain_ device type, the passphrase obtained via --key-file option is passed directly in dm-crypt.
|
|
|
|
|
With _plain_ device type, the passphrase obtained via --key-file option is passed directly in dm-crypt.
|
|
|
|
|
Unlike the interactive mode (stdin), where the digest of the passphrase is passed in dm-crypt instead.
|
|
|
|
|
+
|
|
|
|
|
endif::[]
|
|
|
|
|
@@ -536,9 +537,9 @@ ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKS
|
|
|
|
|
ifdef::ACTION_LUKSADDKEY[]
|
|
|
|
|
When used together with the parameter --new-key-slot, this option allows you to specify which keyslot is selected for unlocking the volume key.
|
|
|
|
|
+
|
|
|
|
|
*NOTE:* This option is ignored if the 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.
|
|
|
|
|
This option is ignored if the 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 keyslot is selected for the new key.
|
|
|
|
|
To maintain backward compatibility, without --new-key-slot parameter, this option allows you to specify which keyslot is selected for the new key.
|
|
|
|
|
endif::[]
|
|
|
|
|
ifndef::ACTION_OPEN,ACTION_LUKSADDKEY[]
|
|
|
|
|
For LUKS operations that add key material, this option allows you to specify which keyslot is selected for the new key.
|
|
|
|
|
@@ -657,8 +658,6 @@ ifdef::ACTION_LUKSADDKEY[]
|
|
|
|
|
*--new-key-slot* _<0-N>_::
|
|
|
|
|
This option allows you to specify which keyslot is selected for the new key.
|
|
|
|
|
+
|
|
|
|
|
*NOTE:* When used this option affects --key-slot option.
|
|
|
|
|
+
|
|
|
|
|
The maximum number of keyslots depends on the LUKS version.
|
|
|
|
|
LUKS1 can have up to 8 keyslots.
|
|
|
|
|
LUKS2 can have up to 32 keyslots based on keyslot area size and key size, but a valid keyslot ID can always be between 0 and 31 for LUKS2.
|
|
|
|
|
@@ -732,7 +731,7 @@ The parallel cost --pbkdf-parallel is constant and is checked against available
|
|
|
|
|
+
|
|
|
|
|
You can see all PBKDF parameters for a particular LUKS2 keyslot with the *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.
|
|
|
|
|
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 or cause out-of-memory conditions with unconditional process termination.
|
|
|
|
|
Use only in specific cases, for example, if you know that the formatted device will be used on some small embedded system.
|
|
|
|
|
@@ -772,7 +771,7 @@ ifdef::ACTION_REFRESH,ACTION_OPEN[]
|
|
|
|
|
Set dm-crypt workqueues and the writer thread to high priority.
|
|
|
|
|
This improves throughput and latency of dm-crypt while degrading the general responsiveness of the system.
|
|
|
|
|
+
|
|
|
|
|
*NOTE:* This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.
|
|
|
|
|
This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.
|
|
|
|
|
Needs kernel 6.10 or later.
|
|
|
|
|
endif::[]
|
|
|
|
|
|
|
|
|
|
@@ -780,7 +779,7 @@ ifdef::ACTION_REFRESH,ACTION_OPEN[]
|
|
|
|
|
*--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 the default dm-crypt behaviour.
|
|
|
|
|
These options are available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.
|
|
|
|
|
Needs kernel 5.9 or later.
|
|
|
|
|
endif::[]
|
|
|
|
|
|
|
|
|
|
@@ -789,7 +788,7 @@ ifdef::ACTION_REFRESH,ACTION_OPEN[]
|
|
|
|
|
Perform encryption using the same CPU on which that IO was submitted.
|
|
|
|
|
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 the default dm-crypt behaviour.
|
|
|
|
|
This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.
|
|
|
|
|
endif::[]
|
|
|
|
|
|
|
|
|
|
ifdef::ACTION_REFRESH,ACTION_OPEN[]
|
|
|
|
|
@@ -798,7 +797,7 @@ 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 the default dm-crypt behaviour.
|
|
|
|
|
This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour.
|
|
|
|
|
endif::[]
|
|
|
|
|
|
|
|
|
|
ifdef::ACTION_OPEN,ACTION_REFRESH[]
|
|
|
|
|
@@ -871,7 +870,6 @@ The former first data segment is replaced with LUKS2 header (half the _size_ val
|
|
|
|
|
+
|
|
|
|
|
The recommended minimum size is twice the default LUKS2 header size (--reduce-device-size 32M) for encryption mode.
|
|
|
|
|
+
|
|
|
|
|
*NOTE*:
|
|
|
|
|
The sum of --device-size and --reduce-device-size values must not exceed the real device size.
|
|
|
|
|
+
|
|
|
|
|
*LUKS1*:
|
|
|
|
|
@@ -956,7 +954,7 @@ ifdef::ACTION_OPEN[]
|
|
|
|
|
*--serialize-memory-hard-pbkdf*::
|
|
|
|
|
Use a global lock to serialize unlocking of keyslots using memory-hard PBKDF.
|
|
|
|
|
+
|
|
|
|
|
*NOTE:* This is a workaround for a specific situation when multiple devices are activated in parallel, and the system, instead of reporting out of memory, starts unconditionally stop processes using the out-of-memory killer.
|
|
|
|
|
This is a workaround for a specific situation when multiple devices are activated in parallel, and the system, instead of reporting out of memory, starts unconditionally stop processes using the out-of-memory killer.
|
|
|
|
|
+
|
|
|
|
|
*DO NOT USE* this switch until you are implementing the boot environment with parallel devices activation!
|
|
|
|
|
endif::[]
|
|
|
|
|
@@ -1067,7 +1065,7 @@ endif::[]
|
|
|
|
|
ifdef::ACTION_LUKSADDKEY[]
|
|
|
|
|
Use only LUKS2 tokens to unlock the existing volume key.
|
|
|
|
|
+
|
|
|
|
|
*NOTE*: To create a new keyslot using the passphrase provided by a token, use --new-token-id parameter.
|
|
|
|
|
To create a new keyslot using the passphrase provided by a token, use --new-token-id parameter.
|
|
|
|
|
endif::[]
|
|
|
|
|
endif::[]
|
|
|
|
|
|
|
|
|
|
|
Milan Broz