diff --git a/man/common_footer.adoc b/man/common_footer.adoc index ef4a2a6e..6747aee1 100644 --- a/man/common_footer.adoc +++ b/man/common_footer.adoc @@ -2,7 +2,7 @@ Report bugs at mailto:cryptsetup@lists.linux.dev[cryptsetup mailing list] or in https://gitlab.com/cryptsetup/cryptsetup/-/issues/new[Issues project section]. -Please attach output of the failed command with --debug option added. +Please attach the output of the failed command with --debug option added. == SEE ALSO diff --git a/man/common_options.adoc b/man/common_options.adoc index b433e63c..6602943b 100644 --- a/man/common_options.adoc +++ b/man/common_options.adoc @@ -5,13 +5,13 @@ ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] 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). +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. +*WARNING:* This option is DEPRECATED and has an unexpected impact on the data offset and keyslot area size (for LUKS2) due to the complex rounding. +For fixed data device offset, use --offset option instead. endif::[] ifdef::ACTION_OPEN,ACTION_REFRESH[] @@ -20,7 +20,7 @@ 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. +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. @@ -44,30 +44,30 @@ endif::[] ifdef::ACTION_CLOSE[] *--cancel-deferred*:: -Removes a previously configured deferred device removal in _close_ command. +Removes a previously configured deferred device removal in the _close_ command. endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_TCRYPTDUMP,ACTION_BENCHMARK[] *--cipher*, *-c* __:: ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] -Set the cipher specification string for _plain_ device type. +Set the cipher specification string for the _plain_ device type. + -For _tcrypt_ device type it restricts checked cipher chains when looking for header. +For the _tcrypt_ device type, it restricts checked cipher chains when looking for the header. endif::[] ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_TCRYPTDUMP[] Set the cipher specification string. endif::[] ifdef::ACTION_REENCRYPT[] *LUKS2*: -Set the cipher specification string for data segment only. +Set the cipher specification string for the data segment only. + *LUKS1*: -Set the cipher specification string for data segment and keyslots. +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. +*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 default cipher would be applied as in encrypt mode. +In that case, the default cipher would be applied as in encrypt mode. endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] + @@ -76,7 +76,7 @@ _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. +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. endif::[] endif::[] @@ -96,42 +96,42 @@ endif::[] ifdef::ACTION_CLOSE[] *--deferred*:: -Defers device removal in _close_ command until the last user closes it. +Defers device removal in the _close_ command until the last user closes it. endif::[] ifdef::ACTION_OPEN,ACTION_REENCRYPT,ACTION_RESIZE[] *--device-size* _size[units]_:: ifndef::ACTION_RESIZE[] -Instead of real device size, use specified value. +Instead of the real device size, use the specified value. endif::[] ifdef::ACTION_RESIZE[] -Sets new size of the device. -If unset real device size is used. +Sets the new size of the device. +If unset, the real device size is used. endif::[] ifdef::ACTION_OPEN[] Usable only with _plain_ device type. endif::[] ifdef::ACTION_REENCRYPT[] -It means that only specified area (from the start of the device to the specified size) will be reencrypted. +It means that only the specified area (from the start of the device to the specified size) will be reencrypted. + *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 real device size. +The sum of --device-size and --reduce-device-size values must not exceed the real device size. + -*WARNING:* This is destructive operation. -Data beyond --device-size limit may be lost after operation gets finished. +*WARNING:* This is a destructive operation. +Data beyond --device-size limit may be lost after the operation is finished. endif::[] + 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). +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). endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] *--disable-blkid*:: -Disable use of blkid library for checking and wiping on-disk signatures. +Disable use of the blkid library for checking and wiping on-disk signatures. endif::[] ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_RESIZE,ACTION_TOKEN[] @@ -141,17 +141,17 @@ endif::[] ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_REFRESH,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_REENCRYPT[] *--disable-keyring*:: -Do not load volume key in kernel keyring and store it directly in the dm-crypt target instead. +Do not load the volume key in the kernel keyring; store it directly in the dm-crypt target instead. This option is supported only for the LUKS2 type. endif::[] ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP,ACTION_TCRYPTDUMP[] *--disable-locks*:: Disable lock protection for metadata on disk. -This option is valid only for LUKS2 and ignored for other formats. +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 need for super user privileges provided used block ciphers are available in crypto backend. +*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. + 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). @@ -160,12 +160,12 @@ endif::[] ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] *--disable-veracrypt*:: This option can be used to disable VeraCrypt compatible mode (only TrueCrypt devices are recognized). -See _TCRYPT_ section in *cryptsetup*(8) for more info. +See the _TCRYPT_ section in *cryptsetup*(8) for more info. endif::[] ifdef::ACTION_LUKSDUMP[] *--dump-json-metadata*:: -For _luksDump_ (LUKS2 only) this option prints content of LUKS2 header JSON metadata area. +For _luksDump_ (LUKS2 only), this option prints the content of the LUKS2 header JSON metadata area. endif::[] ifdef::ACTION_LUKSDUMP,ACTION_TCRYPTDUMP,ACTION_BITLKDUMP[] @@ -177,25 +177,25 @@ endif::[] ifdef::ACTION_REENCRYPT[] *--encrypt*, *--new*, *-N*:: -Initialize (and run) device in-place encryption mode. +Initialize (and run) the device in-place encryption mode. endif::[] ifdef::ACTION_RESIZE,ACTION_OPEN,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_LUKSRESUME,ACTION_TOKEN[] *--external-tokens-path* __:: -Override system directory path where cryptsetup searches for external token handlers (or token plugins). -It must be absolute path (starting with '/' character). +Override the system directory path where cryptsetup searches for external token handlers (or token plugins). +It must be an absolute path (starting with '/' character). endif::[] ifdef::ACTION_REENCRYPT[] *--force-no-keyslots* (LUKS2 only):: 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 deletion of all remaining LUKS2 keyslots containing volume key. +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. See *cryptsetup-luksAddKey*(8) command. + *WARNING:* Use with extreme caution! -If you loose volume key stored in a file or in a kernel keyring before adding LUKS2 keyslot containing new volume key the device will become unusable and all data will be lost. +If you lose the volume key stored in a file or in a kernel keyring before adding the LUKS2 keyslot containing the new volume key, the device will become unusable, and all data will be lost. endif::[] ifdef::ACTION_REENCRYPT[] @@ -204,7 +204,7 @@ Bypass active device auto-detection and enforce offline reencryption. + This option is useful especially for reencryption of LUKS2 images put in files (auto-detection is not reliable in this scenario). + -It may also help in case active device auto-detection on particular data device does not work or report errors. +It may also help in case active device auto-detection on a particular data device does not work or report errors. + *WARNING:* Use with extreme caution! This may destroy data if the device is activated and/or actively used. endif::[] @@ -215,7 +215,7 @@ 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)*. +For more info about password quality check, see the manual page for *pwquality.conf*(5) and *passwdqc.conf*(5). endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_TCRYPTDUMP,ACTION_BENCHMARK,ACTION_REENCRYPT[] @@ -224,19 +224,19 @@ ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] 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. +For the _tcrypt_ device type, it restricts the checked PBKDF2 variants when looking for the header. endif::[] ifdef::ACTION_LUKSFORMAT[] Specifies the hash used in the LUKS key setup scheme and volume key digest. endif::[] ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_TCRYPTDUMP[] -The specified hash is used for PBKDF2 and AF splitter. +The specified hash is used for PBKDF2 and the AF splitter. endif::[] 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, default hash algorithm is always used for new LUKS1 device header. +*NOTE*: 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::[] @@ -252,11 +252,11 @@ ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP[] *--header* __:: ifndef::ACTION_OPEN,ACTION_ERASE[] 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. +This option allows one to store the ciphertext and LUKS header on different devices. + endif::[] ifdef::ACTION_OPEN[] -Specify detached (separated) metadata device or file where the header is stored. +Specify a 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. @@ -267,10 +267,10 @@ ifdef::ACTION_LUKSFORMAT[] 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. +The --align-payload option is taken as absolute sector alignment on the ciphertext device and can be zero. endif::[] ifndef::ACTION_LUKSFORMAT,ACTION_OPEN,ACTION_ERASE[] -For commands that change the LUKS header (e.g. _luksAddKey_), specify the device or file with the LUKS header directly as the LUKS device. +For commands that change the LUKS header (e.g., _luksAddKey_), specify the device or file with the LUKS header directly as the LUKS device. endif::[] endif::[] ifdef::ACTION_REENCRYPT[] @@ -278,22 +278,22 @@ If used with --encrypt/--new option, the header file will be created (or overwri Use with care. + *LUKS2*: -For decryption mode the option may be used to export original LUKS2 header to a detached file. +For decryption mode, the option may be used to export the original LUKS2 header to a detached file. The passed future file must not exist at the time of initializing the decryption operation. -This frees space in head of data device so that data can be moved at original LUKS2 header location. -Later on decryption operation continues as if the ordinary detached header was passed. +This frees space in the head of the data device so that data can be moved at the original LUKS2 header location. +Later on, the decryption operation continues as if the ordinary detached header was passed. + -*WARNING:* Never put exported header file in a filesystem on top of device you are about to decrypt! +*WARNING:* Never put an exported header file in a filesystem on top of the device you are about to decrypt! It would cause a deadlock. endif::[] ifdef::ACTION_ERASE[] -Use to specify detached LUKS2 header when erasing HW OPAL enabled data device. +Use to specify a detached LUKS2 header when erasing HW OPAL-enabled data device. endif::[] endif::[] ifdef::ACTION_LUKSHEADERBACKUP,ACTION_LUKSHEADERRESTORE[] *--header-backup-file* _file_:: -Specify file with header backup file. +Specify a file with the header backup file. endif::[] ifdef::COMMON_OPTIONS[] @@ -303,16 +303,16 @@ endif::[] ifdef::ACTION_REENCRYPT[] *--hotzone-size* _size_ (LUKS2 only):: -This option can be used to set an upper limit on the size of reencryption area (hotzone). -The _size_ can be specified with unit suffix (for example 50M). -Note that actual hotzone size may be less than specified due to other limitations (free space in keyslots area or available memory). +This option can be used to set an upper limit on the size of the reencryption area (hotzone). +The _size_ can be specified with a unit suffix (for example, 50M). +Note that the actual hotzone size may be less than specified due to other limitations (free space in keyslots area or available memory). + -With decryption mode for devices with LUKS2 header placed in head of data device, the option specifies how large is the first data segment moved from original data offset pointer. +With decryption mode for devices with LUKS2 header placed in the head of the data device, the option specifies how large is the first data segment moved from the original data offset pointer. endif::[] ifdef::ACTION_LUKSFORMAT[] *--hw-opal*:: -Format LUKS2 device with dm-crypt encryption stacked on top HW based encryption configured on SED OPAL locking range. +Format LUKS2 device with dm-crypt encryption stacked on top of HW-based encryption configured on SED OPAL locking range. This option enables both SW and HW based data encryption. endif::[] @@ -320,7 +320,7 @@ ifdef::ACTION_ERASE[] *--hw-opal-factory-reset*:: Erase *ALL* data on the OPAL self-encrypted device. The option does not require a valid LUKS2 header to be present on the device to run. -After providing correct PSID via interactive prompt or via --key-file parameter the device is erased. +After providing the correct PSID via interactive prompt or via --key-file parameter the device is erased. + PSID is usually printed on the OPAL device label (either directly or as a QR code). PSID must be entered without any dashes, spaces or underscores. @@ -332,8 +332,8 @@ endif::[] ifdef::ACTION_LUKSFORMAT[] *--hw-opal-only*:: Format LUKS2 device with HW based encryption configured on SED OPAL locking range only. -LUKS2 format only manages locking range unlock key. -This option enables HW based data encryption managed by SED OPAL drive only. +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). 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. @@ -347,17 +347,17 @@ endif::[] ifdef::ACTION_LUKSFORMAT[] *--integrity* __:: -Specify integrity algorithm to be used for authenticated disk encryption in LUKS2. +Specify the 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 native AEAD modes, also enable "User-space interface for AEAD cipher algorithms" in the "Cryptographic API" section (CONFIG_CRYPTO_USER_API_AEAD .config option). + -For more info, see _AUTHENTICATED DISK ENCRYPTION_ section in *cryptsetup*(8). +For more info, see the _AUTHENTICATED DISK ENCRYPTION_ section in *cryptsetup*(8). endif::[] ifdef::ACTION_LUKSFORMAT[] *--integrity-inline*:: -Store integrity tags to hardware sector integrity fields. +Store integrity tags in hardware sector integrity fields. The device must support sectors with additional protection information (PI, also known as DIF - data integrity field) of the requested size. Another storage subsystem must not use the additional field (the device must present a "nop" profile in the kernel). Note that some devices must be reformatted at a low level to support this option; for NVMe devices, see nvme(1) id-ns LBA profiles. @@ -371,36 +371,36 @@ ifdef::ACTION_LUKSFORMAT[] *--integrity-key-size* _bytes_:: The size of the data integrity key. Configurable only for HMAC integrity. -Default integrity key size is set to the same as hash output length. +The default integrity key size is set to the same as the hash output length. endif::[] ifdef::ACTION_LUKSFORMAT[] *--integrity-legacy-padding*:: Use inefficient legacy padding. + -*WARNING*: Do not use this option until you need compatibility with specific old kernel. +*WARNING*: Do not use this option until you need compatibility with a specific old kernel. endif::[] ifdef::ACTION_REFRESH[] *--integrity-no-journal*:: Activate device with integrity protection without using data journal (direct write of data and integrity tags). -Note that without journal power fail can cause non-atomic write and data corruption. -Use only if journalling is performed on a different storage layer. +Note that without a journal, a power failure can cause non-atomic writes and data corruption. +Use only if journaling is performed on a different storage layer. endif::[] ifdef::ACTION_LUKSFORMAT[] *--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. +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 page size and page-cache initiates read of a sector with invalid integrity tag. +*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. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] *--iter-time*, *-i* __:: ifndef::ACTION_REENCRYPT[] The number of milliseconds to spend with PBKDF passphrase processing. -Specifying 0 as parameter selects the compiled-in default. +Specifying 0 as a parameter selects the compiled-in default. endif::[] ifdef::ACTION_REENCRYPT[] The number of milliseconds to spend with PBKDF passphrase processing for the new LUKS header. @@ -409,22 +409,22 @@ endif::[] ifdef::ACTION_OPEN[] *--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. +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. +*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. endif::[] ifdef::ACTION_TOKEN[] *--json-file*:: -Read token JSON from a file or write token to it. -Option --json-file=- reads JSON from standard input or writes it to standard output respectively. +Read the token JSON from a file or write the token to it. +Option --json-file=- reads JSON from standard input or writes it to standard output, respectively. endif::[] ifdef::ACTION_REENCRYPT[] *--keep-key*:: *LUKS2*: -Do not change effective volume key and change other parameters provided it is requested. +Do not change the effective volume key, and change other parameters if requested. + *LUKS1*: Reencrypt only the LUKS1 header and keyslots. @@ -433,44 +433,44 @@ endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSDUMP,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_TOKEN[] *--key-description* _text_:: -Set key description in keyring that will be used for passphrase retrieval. +Set the key description in the keyring that will be used for passphrase retrieval. endif::[] ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_TCRYPTDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[] *--key-file*, *-d* _file_:: -Read the passphrase from file. +Read the passphrase from the file. + If the name given is "-", then the passphrase will be read from stdin. In this case, reading will not stop at newline characters. + ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY[] -The passphrase supplied via --key-file is always the passphrase for existing keyslot requested by the command. +The passphrase supplied via --key-file is always the passphrase for the existing keyslot requested by the command. + ifdef::ACTION_LUKSADDKEY[] If you want to set a new passphrase via key file, you have to use a positional argument or parameter --new-keyfile. endif::[] ifdef::ACTION_LUKSCHANGEKEY[] -If you want to set a new passphrase via key file, you have to use a positional argument. +If you want to set a new passphrase via a key file, you have to use a positional argument. endif::[] + endif::[] ifdef::ACTION_OPEN[] *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. +Unlike the interactive mode (stdin), where the digest of the passphrase is passed in dm-crypt instead. + endif::[] ifndef::ACTION_REENCRYPT[] See section _NOTES ON PASSPHRASE PROCESSING_ in *cryptsetup*(8) for more information. endif::[] ifdef::ACTION_REENCRYPT[] -*WARNING:* --key-file option can be used only if there is only one active keyslot, or alternatively, also if --key-slot option is specified (then all other keyslots will be disabled in new LUKS device). +*WARNING:* --key-file option can be used only if there is only one active keyslot, or alternatively, also if --key-slot option is specified (then all other keyslots will be disabled in the new LUKS device). + If this option is not used, cryptsetup will ask for all active keyslot passphrases. endif::[] endif::[] ifdef::ACTION_ERASE[] *--key-file*, *-d* _file_ (LUKS2 with HW OPAL only):: -Read the Admin PIN or PSID (with --hw-opal-factory-reset) from file depending on options used. +Read the Admin PIN or PSID (with --hw-opal-factory-reset) from the file, depending on options used. + If the name given is "-", then the secret will be read from stdin. In this case, reading will not stop at newline characters. @@ -497,34 +497,34 @@ ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_BENCHMARK,ACTION_LU ifndef::ACTION_LUKSADDKEY,ACTION_REENCRYPT[] 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. +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. +Note that the key size in /proc/crypto is stated in bytes. + endif::[] ifdef::ACTION_LUKSADDKEY[] 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. +This option is required when the parameter --volume-key-file is used to provide current volume key. +Also, it is used when a new unbound keyslot is created by specifying --unbound parameter. endif::[] ifdef::ACTION_OPEN[] This option can be used for _plain_ and _luks_ devices. -For LUKS2 devices in reencryption you may use the parameter twice to specify both old and new volume key sizes. +For LUKS2 devices in reencryption, you may use the parameter twice to specify both old and new volume key sizes. Each --key-size option corresponds to the respective --volume-key-file parameter (also allowed to be used up to two times). endif::[] ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_LUKSADDKEY[] 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. +All other LUKS actions will use the key size specified in the LUKS header. Use _cryptsetup --help_ to show the compiled-in defaults. endif::[] ifdef::ACTION_REENCRYPT[] *LUKS2*: Provide current key size in _bits_. The argument has to be a multiple of 8. -Useful when specifying the size of current volume key when no keyslot is active. +Useful when specifying the size of the current volume key when no keyslot is active. + *LUKS1*: See --new-key-size. @@ -534,28 +534,28 @@ endif::[] ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSDUMP,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_CONFIG,ACTION_TOKEN,ACTION_REPAIR,ACTION_REENCRYPT[] *--key-slot*, *-S* _<0-N>_:: ifdef::ACTION_LUKSADDKEY[] -When used together with parameter --new-key-slot this option allows you to specify which key slot is selected for unlocking volume key. +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 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:* 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 key slot is selected for the new key. +*NOTE:* 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 key slot is selected for the new key. +For LUKS operations that add key material, this option allows you to specify which keyslot is selected for the new key. endif::[] ifdef::ACTION_OPEN[] -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. +This option selects a specific keyslot to compare the passphrase against. +If the given passphrase would only matches a different keyslot, the operation fails. endif::[] + ifdef::ACTION_REENCRYPT[] -For reencryption mode it selects specific keyslot (and passphrase) that can be used to unlock new volume key. -If used all other keyslots get removed after reencryption operation is finished. +For reencryption mode, it selects a specific keyslot (and passphrase) that can be used to unlock the new volume key. +If used, all other keyslots get removed after the reencryption operation is finished. + endif::[] -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. +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. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] @@ -565,7 +565,7 @@ endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] *--keyslot-key-size* __:: -This option can be used to set specific key size for the LUKS2 keyslot area. +This option can be used to set a specific key size for the LUKS2 keyslot area. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_CONFIG,ACTION_REENCRYPT[] @@ -576,91 +576,91 @@ endif::[] ifdef::ACTION_OPEN,ACTION_LUKSRESUME[] *--link-vk-to-keyring* _::_:: -Link volume key in a keyring with specified key name. -The volume key is linked only if requested action is successfully finished (with --test-passphrase the verified volume key is linked in a keyring without taking further action). +Link the volume key in a keyring with the specified key name. +The volume key is linked only if the requested action is successfully finished (with --test-passphrase, the verified volume key is linked in a keyring without taking further action). + -The __ string has to contain existing kernel keyring description. +The __ string has to contain the existing kernel keyring description. The keyring name may be optionally prefixed with "%:" or "%keyring:" type descriptions. Or, the keyring may also be specified directly by numeric key id. -Also special keyring notations starting with "@" may be used to select existing predefined kernel keyrings. +Also, special keyring notations starting with "@" may be used to select existing predefined kernel keyrings. + -The string "::" is delimiter used to separate keyring description and key description. +The string "::" is a delimiter used to separate the keyring description and key description. + __ part describes key type and key name of volume key linked in the keyring described in __. -The type may be specified by adding "%:" prefix in front of key name. -If type is missing default _user_ type is applied. -If the key of same name and same type already exists (already linked in the keyring) it will get replaced in the process. +The type may be specified by adding a "%:" prefix in front of the key name. +If the type is missing, the default _user_ type is applied. +If the key of the same name and type already exists (already linked in the keyring), it will get replaced in the process. + -See also *KEY IDENTIFIERS* section of *keyctl*(1). +See also the *KEY IDENTIFIERS* section of *keyctl*(1). endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] *--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 can be specified with unit suffix (for example 128k). +This option can be used to set a specific size of the LUKS2 binary keyslot area (key material is encrypted there). +The value must be aligned to a multiple of 4096 bytes with a maximum size 128MB. +The can be specified with a unit suffix (for example, 128k). endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] *--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 can be specified with unit suffix (for example 128k). +According to the LUKS2 specification, only these values are valid: 16, 32, 64, 128, 256, 512, 1024, 2048 and 4096 kB. +The can be specified with a unit suffix (for example, 128k). endif::[] ifdef::ACTION_LUKSADDKEY[] *--new-keyfile* _name_:: -Read the passphrase for a new keyslot from file. +Read the passphrase for a new keyslot from a 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. +This is an alternative method to positional argument when adding a new passphrase via keyfile. endif::[] ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY[] *--new-keyfile-offset* _value_:: -Skip _value_ bytes at the start when adding a new passphrase from key file. +Skip _value_ bytes at the start when adding a new passphrase from the key file. endif::[] ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY[] *--new-keyfile-size* _value_:: -Read a maximum of _value_ bytes when adding a new passphrase from key file. +Read a maximum of _value_ bytes when adding a new passphrase from the 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. +Supplying more than the compiled-in maximum aborts the operation. When --new-keyfile-offset is also given, reading starts after the offset. endif::[] ifdef::ACTION_LUKSADDKEY[] *--new-key-description* _text_:: -Set key description in keyring that will be used for new passphrase retrieval. +Set the key description in the keyring that will be used for new passphrase retrieval. endif::[] ifdef::ACTION_REENCRYPT[] *--new-key-size* _bits_:: Sets new key size in _bits_. The argument has to be a multiple of 8. -The possible key-sizes are limited by the new cipher and mode used in reencryption. +The possible key sizes are limited by the new cipher and mode used in reencryption. + See /proc/crypto for more information. -Note that key-size in /proc/crypto is stated in bytes. +Note that the key size in /proc/crypto is stated in bytes. + *LUKS1*: -If you are increasing key size, there must be enough space in the LUKS header for enlarged keyslots (data offset must be large enough) or reencryption cannot be performed. +If you are increasing key size, there must be enough space in the LUKS header for enlarged keyslots (data offset must be large enough), or reencryption cannot be performed. + -If there is not enough space for keyslots with new key size, you can destructively shrink device with --reduce-device-size option. +If there is not enough space for keyslots with the new key size, you can destructively shrink the device with --reduce-device-size option. endif::[] ifdef::ACTION_LUKSADDKEY[] *--new-key-slot* _<0-N>_:: -This option allows you to specify which key slot is selected for the new key. +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 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. +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. endif::[] ifdef::ACTION_LUKSADDKEY[] @@ -670,28 +670,28 @@ endif::[] ifdef::ACTION_REENCRYPT[] *--new-volume-key-file* _file_:: -Use (set) new volume key stored in a file. -The option must be paired with --new-key-size parameter when initializing reencryption operation. +Use (set) the new volume key stored in a file. +The option must be paired with --new-key-size parameter when initializing the reencryption operation. + *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. +Otherwise, you can end up with a low-entropy or otherwise partially predictable volume key, which will compromise security. endif::[] ifdef::ACTION_REENCRYPT[] *--new-volume-key-keyring* __:: -Use (set) new volume key stored in a keyring. +Use (set) the new volume key stored in a keyring. + -The size of key stored in a keyring must be compatible with new cipher used in reencryption operation. +The size of the key stored in a keyring must be compatible with the new cipher used in the reencryption operation. See /proc/crypto for more information. -Note that key-size in /proc/crypto is stated in bytes. +Note that the key size in /proc/crypto is stated in bytes. + The __ uses keyctl-compatible syntax. This can either be a numeric key ID or a string name in the format _%:_. -See also *KEY IDENTIFIERS* section of *keyctl*(1). -When no _%:_ prefix is specified we assume the key type is _user_ (default type). +See also the *KEY IDENTIFIERS* section of *keyctl*(1). +When no _%:_ prefix is specified, we assume the key type is _user_ (default type). + *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. +Otherwise, you can end up with a low-entropy or otherwise partially predictable volume key, which will compromise security. endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] @@ -705,7 +705,7 @@ This option is only relevant for the encrypt mode. endif::[] + ifndef::ACTION_OPEN[] -The --offset option sets the data offset (payload) of data device and must be aligned to 4096-byte sectors (must be multiple of 8). +The --offset option sets the data offset (payload) of the data device and must be aligned to 4096-byte sectors (must be a multiple of 8). This option cannot be combined with --align-payload option. endif::[] endif::[] @@ -716,12 +716,12 @@ 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 https://www.cryptolux.org/index.php/Argon2[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. +The default PBKDF for LUKS2 is set during compilation time and is available in the _cryptsetup --help_ output. + -A PBKDF is used for increasing dictionary and brute-force attack cost for keyslot passwords. +A PBKDF is used for increasing the 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 PBKDF2, only the 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. @@ -729,49 +729,49 @@ The benchmark tries to find iteration time (--iter-time) with required memory co 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. +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. 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. + -*MINIMAL AND MAXIMAL PBKDF COSTS:* For *PBKDF2*, the minimum iteration count is 1000 and maximum is 4294967295 (maximum for 32bit unsigned integer). +*MINIMAL AND MAXIMAL PBKDF COSTS:* For *PBKDF2*, the minimum iteration count is 1000 and maximum is 4294967295 (maximum for 32-bit 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). +For *Argon2i* and *Argon2id*, the minimum iteration count (CPU cost) is 4, and the maximum is 4294967295 (maximum for a 32-bit 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). +If the memory cost parameter is benchmarked (not specified by a parameter), it is always in the range from 64 MiB to 1 GiB. +The parallel cost minimum is 1 and maximum 4 (if enough CPU cores are available, otherwise it is decreased). endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] *--pbkdf-force-iterations* _number_:: -Avoid PBKDF benchmark and set time cost (iterations) directly. -It can be used for LUKS/LUKS2 device only. +Avoid the PBKDF benchmark and set the time cost (iterations) directly. +It can be used only for a LUKS/LUKS2 device. See --pbkdf option for more info. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] *--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. +Set the memory cost for PBKDF (for Argon2i/id, the number represents kilobytes). +Note that it is the maximal value; PBKDF benchmark or available physical memory can decrease it. This option is not available for PBKDF2. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] *--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. +Note that it is the maximal value; it is decreased automatically if the CPU online count is lower. This option is not available for PBKDF2. endif::[] ifdef::ACTION_REFRESH,ACTION_OPEN[] *--perf-high_priority*:: Set dm-crypt workqueues and the writer thread to high priority. -This i mproves throughput and latency of dm-crypt while degrading general responsiveness of the system. +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 default dm-crypt behaviour. +*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. Needs kernel 6.10 or later. endif::[] @@ -779,16 +779,16 @@ 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 default dm-crypt behaviour. +*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. Needs kernel 5.9 or later. endif::[] ifdef::ACTION_REFRESH,ACTION_OPEN[] *--perf-same_cpu_crypt*:: -Perform encryption using the same cpu that IO was submitted on. +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 default dm-crypt behaviour. +*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. Needs kernel 4.0 or later. endif::[] @@ -798,16 +798,16 @@ 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. +*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. Needs kernel 4.0 or later. endif::[] ifdef::ACTION_OPEN,ACTION_REFRESH[] *--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. +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). +If you need to remove a persistent flag, use --persistent without the flag you want to remove (e.g., to disable the 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. endif::[] @@ -815,25 +815,25 @@ endif::[] ifdef::ACTION_CONFIG[] *--priority* __:: Set a priority for LUKS2 keyslot. -The _prefer_ priority marked slots are tried before _normal_ priority. -The _ignored_ priority means, that slot is never used, if not explicitly requested by --key-slot option. +The _prefer_ priority marked slots are tried before the _normal_ priority. +The _ignored_ priority means that the slot is never used, if not explicitly requested by --key-slot option. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] *--progress-frequency* _seconds_:: ifndef::ACTION_REENCRYPT[] -Print separate line every _seconds_ with wipe progress. +Print a separate line every _seconds_ with wipe progress. endif::[] ifdef::ACTION_REENCRYPT[] -Print separate line every _seconds_ with reencryption progress. +Print a separate line every _seconds_ with reencryption progress. endif::[] endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] *--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): +Prints progress data in JSON format, which is suitable mostly for machine processing. +It prints a separate line every half second (or based on --progress-frequency value). +The JSON output looks as follows during progress (except it's a compact single line): + .... { @@ -846,7 +846,7 @@ The JSON output looks as follows during progress (except it's compact single lin } .... + -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. +Note on numbers in JSON output: Due to JSON parser limitations, all numbers are represented in a string format due to the need for full 64-bit unsigned integers. endif::[] ifdef::ACTION_OPEN[] @@ -856,34 +856,34 @@ endif::[] ifdef::ACTION_REENCRYPT[] *--reduce-device-size* _size_:: -This means that last _size_ sectors on the original device will be lost, data will be effectively shifted by specified number of sectors. +This means that the last _size_ sectors on the original device will be lost, and data will be effectively shifted by the specified number of sectors. + -It could be useful if you added some space to underlying partition or logical volume (so last _size_ sectors contains no data). +It could be useful if you added some space to the underlying partition or logical volume (so the ast _size_ sectors contains no data). + -For units suffix see --device-size parameter description. +For units suffix, see --device-size parameter description. + *WARNING:* This is a destructive operation and cannot be reverted. Use with extreme care - accidentally overwritten filesystems are usually unrecoverable. + *LUKS2*: -Initialize LUKS2 reencryption with data device size reduction (currently only encryption mode is supported). -The last _size_ sectors on the original plaintext device is used for temporarily storing original first data segment. -The former first data segment is replaced with LUKS2 header (half the _size_ value) and plaintext data are shifted backwards (again half the _size_ value) while being encrypted. +Initialize LUKS2 reencryption with data device size reduction (currently, only encryption mode is supported). +The last _size_ sectors on the original plaintext device is used for temporarily storing the original first data segment. +The former first data segment is replaced with LUKS2 header (half the _size_ value), and plaintext data is shifted backwards (again half the _size_ value) while being encrypted. + -Recommended minimal size is twice the default LUKS2 header size (--reduce-device-size 32M) for encryption mode. +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 real device size. +The sum of --device-size and --reduce-device-size values must not exceed the real device size. + *LUKS1*: -Enlarge data offset to specified value by shrinking device size. +Enlarge the data offset to the specified value by shrinking the device size. + -You cannot shrink device more than by 64 MiB (131072 sectors). +You cannot shrink the device by more than 64 MiB (131072 sectors). endif::[] ifdef::ACTION_OPEN[] *--refresh*:: -Refreshes an active device with new set of parameters. +Refreshes an active device with a new set of parameters. See *cryptsetup-refresh*(8) for more details. endif::[] @@ -894,26 +894,26 @@ Reencryption resilience _mode_ can be one of _checksum_, _journal_ or _none_. _checksum_: default mode, where individual checksums of ciphertext hotzone sectors are stored, so the recovery process can detect which sectors were already reencrypted. It requires that the device sector write is atomic. + -_journal_: the hotzone is journaled in the binary area (so the data are written twice). +_journal_: The hotzone is journaled in the binary area (so the data are written twice). + -_none_: performance mode. -There is no protection and the only way it's safe to interrupt the reencryption is similar to old offline reencryption utility. +_none_: Performance mode. +There is no protection, and the only way it's safe to interrupt the reencryption is similar to an old offline reencryption utility. + -Resilience modes can be changed unless _datashift_ mode is used for operation initialization (encryption with --reduce-device-size option) +Resilience modes can be changed unless _datashift_ mode is used for operation initialization (encryption with --reduce-device-size option). endif::[] ifdef::ACTION_REENCRYPT[] *--resilience-hash* _hash_ (LUKS2 only):: -The _hash_ algorithm used with "--resilience checksum" only. +The _hash_ algorithm is used with "--resilience checksum" only. The default hash is sha256. With other resilience modes, the hash parameter is ignored. endif::[] ifdef::ACTION_REENCRYPT[] *--resume-only* (LUKS2 only):: -Resume reencryption (any mode) operation already described in LUKS2 metadata. +Resume reencryption (any mode) operation that is already described in LUKS2 metadata. If no reencrypt operation is initialized, the command with --resume-only parameter fails. -Useful for resuming reencrypt operation without accidentally triggering new reencryption operation. +Useful for resuming the reencrypt operation without accidentally triggering a new reencryption operation. endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] @@ -923,35 +923,35 @@ endif::[] ifndef::ACTION_REENCRYPT[] ifdef::ACTION_OPEN[] Set encryption sector size for use with _plain_ device type. -It must be power of two and in range 512 - 4096 bytes. +It must be a power of two and in the 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. +Note that if the sector size is higher than the underlying device hardware sector, using this option can increase the risk of incomplete sector writes during a power failure. endif::[] ifdef::ACTION_LUKSFORMAT[] Set sector size for use with disk encryption. -It must be power of two and in range 512 - 4096 bytes. +It must be a power of two and in the 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. +For LUKS2 devices, it's established based on parameters provided by the 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 a 512-byte block size, it remains 512 bytes. +If the data device is a regular file put in the 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. +Note that if the sector size is higher than the underlying device hardware sector and there is no integrity protection that uses data journal, using this option can increase the risk of incomplete sector writes during a power failure. + -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). +If used together with --integrity option and dm-integrity journal, the atomicity of writes is guaranteed in all cases (but it costs write performance - data has to be written twice). endif::[] + -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. +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. endif::[] ifdef::ACTION_REENCRYPT[] *--sector-size* _bytes_ (LUKS2 only):: -Reencrypt device with new encryption sector size enforced. +Reencrypt the device with a new encryption sector size enforced. + -*WARNING:* Increasing encryption sector size may break hosted filesystem. -Do not run reencryption with --force-offline-reencrypt if unsure what block size was filesystem formatted with. +*WARNING:* Increasing encryption sector size may break the hosted filesystem. +Do not run reencryption with --force-offline-reencrypt if unsure what block size the filesystem was formatted with. endif::[] endif::[] @@ -959,9 +959,9 @@ ifdef::ACTION_OPEN[] *--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. +*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. + -*DO NOT USE* this switch until you are implementing boot environment with parallel devices activation! +*DO NOT USE* this switch until you are implementing the boot environment with parallel devices activation! endif::[] ifdef::ACTION_OPEN[] @@ -993,7 +993,7 @@ ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] *--tcrypt-hidden*:: *--tcrypt-system*:: Specify which TrueCrypt on-disk header will be used to open the device. -See _TCRYPT_ section in *cryptsetup*(8) for more info. +See the _TCRYPT_ section in *cryptsetup*(8) for more info. + Using a system-encrypted device with the --tcrypt-system option requires specific settings to work as expected. + @@ -1002,30 +1002,29 @@ The metadata header then contains the offset and size of the encrypted area. Cryptsetup needs to know the specific partition offset to calculate encryption parameters. To properly map a partition, you must specify a real partition device so cryptsetup can calculate this offset. + -While you can use a full device as a parameter (/dev/sdb), always prefer to specify the partition you want to map (/dev/sdb1) as only system partition -mode can be detected this way. +While you can use a full device as a parameter (/dev/sdb), always prefer to specify the partition you want to map (/dev/sdb1), as only the system partition mode can be detected this way. + For mapping images (stored in a file), you can use the additional --header option with the real partition device. If the --header is used (and it is different from the data image), cryptsetup expects that the data image contains a snapshot of the data partition only. + If --header is not used (or points to the same image), cryptsetup expects that the image contains a full disk (including the partition table). -This can map a full encrypted area not directly mountable as a filesystem. -Please prefer creating a loop device with partitions (*losetup -P*, see *losetup(8)* man page) and use a real partition (/dev/loopXp1) as the device parameter. +This can map a full encrypted area that is not directly mountable as a filesystem. +Please prefer creating a loop device with partitions (*losetup -P*, see *losetup*(8) man page) and use a real partition (/dev/loopXp1) as the device parameter. endif::[] ifdef::ACTION_OPEN[] *--test-passphrase*:: -Do not activate the device, just verify passphrase. +Do not activate the device, just verify the passphrase. The device mapping name is not mandatory if this option is used. endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_LUKSRESUME,ACTION_RESIZE,ACTION_TCRYPTDUMP,ACTION_BITLKDUMP[] *--timeout*, *-t* _seconds_:: -The number of seconds to wait before timeout on passphrase input via terminal. +The number of seconds to wait before a 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. +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. endif::[] @@ -1033,22 +1032,22 @@ ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_LUKSADDKE *--token-id*:: ifdef::ACTION_REENCRYPT[] *LUKS2 reencryption initialization:* -Specify what keyslots (associated with selected token) to use for LUKS2 reencryption. -If reencryption operation changes effective volume key only keyslots associated the token and unlocked successfully will be available after the reencryption operation is finished. +Specify what keyslots (associated with the selected token) to use for LUKS2 reencryption. +If the reencryption operation changes the effective volume key, only keyslots associated with the token and unlocked successfully will be available after the reencryption operation is finished. + *LUKS2 reencryption resume:* // paragraph continues below endif::[] ifndef::ACTION_TOKEN,ACTION_LUKSADDKEY[] -Specify what token to use and allow token PIN prompt to take precedence over interactive keyslot passphrase prompt. -If omitted, all available tokens (not protected by PIN) will be checked before proceeding further with passphrase prompt. +Specify what token to use and allow the token PIN prompt to take precedence over the interactive keyslot passphrase prompt. +If omitted, all available tokens (not protected by PIN) will be checked before proceeding further with the passphrase prompt. endif::[] ifdef::ACTION_LUKSADDKEY[] -Specify what token to use when unlocking existing keyslot to get volume key. +Specify what token to use when unlocking the existing keyslot to get the volume key. endif::[] ifdef::ACTION_TOKEN[] -Specify token number. -If omitted, first unused token id is used when adding or importing new token. +Specify the token number. +If omitted, the first unused token id is used when adding or importing a new token. endif::[] endif::[] @@ -1056,22 +1055,22 @@ ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_REEN *--token-only*:: ifdef::ACTION_REENCRYPT[] *LUKS2 reencryption initialization:* -Specify all keyslots associated with any token will be used for LUKS2 reencryption. -If reencryption operation changes effective volume key only keyslots associated with any token will be available after the reencryption operation is finished. +Specify that all keyslots associated with any token will be used for LUKS2 reencryption. +If the reencryption operation changes the effective volume key, only keyslots associated with any token will be available after the reencryption operation is finished. + *LUKS2 reencryption resume:* // paragraph continues below endif::[] ifndef::ACTION_LUKSADDKEY[] -Do not proceed further with action if token based keyslot unlock failed. -Without the option, action asks for passphrase to proceed further. +Do not proceed further with the action if the token-based keyslot unlock failed. +Without the option, the action asks for a passphrase to proceed further. + -It allows LUKS2 tokens protected by PIN to take precedence over interactive keyslot passphrase prompt. +It allows LUKS2 tokens protected by PIN to take precedence over the interactive keyslot passphrase prompt. endif::[] ifdef::ACTION_LUKSADDKEY[] -Use only LUKS2 tokens to unlock existing volume key. +Use only LUKS2 tokens to unlock the existing volume key. + -*NOTE*: To create a new keyslot using passphrase provided by a token use --new-token-id parameter. +*NOTE*: To create a new keyslot using the passphrase provided by a token, use --new-token-id parameter. endif::[] endif::[] @@ -1084,20 +1083,20 @@ ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_REEN *--token-type* _type_:: ifdef::ACTION_REENCRYPT[] *LUKS2 reencryption initialization:* -Specify what keyslots (associated with selected token type) to use for LUKS2 reencryption. -If reencryption operation changes effective volume key only keyslots associated the token type and unlocked successfully will be available after the reencryption operation is finished. +Specify what keyslots (associated with the selected token type) to use for LUKS2 reencryption. +If the reencryption operation changes the effective volume key, only keyslots associated with the token type and unlocked successfully will be available after the reencryption operation is finished. + *LUKS2 reencryption resume:* // paragraph continues below endif::[] ifndef::ACTION_LUKSADDKEY[] -Restrict tokens eligible for operation to specific token _type_. +Restrict tokens eligible for operation to a 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. +It allows LUKS2 _type_ tokens protected by PIN to take precedence over the interactive keyslot passphrase prompt. endif::[] ifdef::ACTION_LUKSADDKEY[] -Specify what token type (all _type_ tokens) to use when unlocking existing keyslot to get volume key. +Specify what token type (all _type_ tokens) to use when unlocking the existing keyslot to get the volume key. endif::[] endif::[] @@ -1110,7 +1109,7 @@ endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSKILLSLOT,ACTION_ISLUKS,ACTION_LUKSDUMP,ACTION_LUKSUUID,ACTION_CONVERT,ACTION_REPAIR,ACTION_REENCRYPT[] *--type* _type_:: ifndef::ACTION_REENCRYPT[] -Specifies required device type, for more info read _BASIC ACTIONS_ section in *cryptsetup*(8). +Specifies required device type, for more info, read the _BASIC ACTIONS_ section in *cryptsetup*(8). endif::[] ifdef::ACTION_REENCRYPT[] Specifies required (encryption mode) or expected (other modes) LUKS format. @@ -1121,18 +1120,18 @@ endif::[] ifdef::ACTION_OPEN,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_TOKEN[] *--unbound*:: ifdef::ACTION_LUKSADDKEY[] -Creates new LUKS2 unbound keyslot. +Creates a new LUKS2 unbound keyslot. endif::[] ifdef::ACTION_LUKSDUMP[] -Dumps existing LUKS2 unbound keyslot. +Dumps the existing LUKS2 unbound keyslot. endif::[] ifdef::ACTION_OPEN[] -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. +Allowed only together with --test-passphrase parameter, it allows one to test the passphrase for an unbound LUKS2 keyslot. +Otherwise, an unbound keyslot passphrase can be tested only when a specific keyslot is selected via --key-slot parameter. endif::[] ifdef::ACTION_TOKEN[] -Creates new LUKS2 keyring token assigned to no keyslot. -Usable only with _add_ action. +Creates a new LUKS2 keyring token assigned to no keyslot. +Usable only with the _add_ action. endif::[] endif::[] @@ -1143,15 +1142,15 @@ endif::[] ifdef::ACTION_REENCRYPT[] *--use-directio* (LUKS1 only):: -Use direct-io (O_DIRECT) for all read/write data operations related to block device undergoing reencryption. +Use direct-io (O_DIRECT) for all read/write data operations related to the block device undergoing reencryption. + -Useful if direct-io operations perform better than normal buffered operations (e.g. in virtual environments). +Useful if direct-io operations perform better than normal buffered operations (e.g., in virtual environments). endif::[] ifdef::ACTION_REENCRYPT[] *--use-fsync* (LUKS1 only):: -Use fsync call after every written block. -This applies for reencryption log files as well. +Use the fsync call after every written block. +This applies to reencryption log files as well. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] @@ -1161,12 +1160,12 @@ ifdef::ACTION_REENCRYPT[] Define which kernel random number generator will be used to create the volume key. endif::[] ifndef::ACTION_REENCRYPT[] -For _luksFormat_ these options define which kernel random number generator will be used to create the volume key (which is a long-term key). +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. +*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. endif::[] @@ -1180,13 +1179,13 @@ Changes the existing _UUID_ when used with the _luksUUID_ command. + endif::[] ifdef::ACTION_REENCRYPT[] -When used in encryption mode use the provided _UUID_ for the new LUKS header instead of generating a new one. +When used in encryption mode, use the provided _UUID_ for the new LUKS header instead of generating a new one. + *LUKS1 (only in decryption mode)*: -To find out what _UUID_ to pass look for temporary files LUKS-_UUID_.[|log|org|new] of the interrupted decryption process. +To find out what _UUID_ to pass, look for temporary files LUKS-_UUID_.[|log|org|new] of the interrupted decryption process. + endif::[] -The _UUID_ must be provided in the standard UUID format, e.g. 12345678-1234-1234-1234-123456789abc. +The _UUID_ must be provided in the standard UUID format, e.g., 12345678-1234-1234-1234-123456789abc. endif::[] ifdef::ACTION_TCRYPTDUMP,ACTION_OPEN[] @@ -1197,8 +1196,8 @@ endif::[] ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] *--veracrypt-pim*:: *--veracrypt-query-pim*:: -Use a custom Personal Iteration Multiplier (PIM) for VeraCrypt device. -See _TCRYPT_ section in *cryptsetup*(8) for more info. +Use a custom Personal Iteration Multiplier (PIM) for the VeraCrypt device. +See the _TCRYPT_ section in *cryptsetup*(8) for more info. endif::[] ifdef::ACTION_ISLUKS[] @@ -1229,7 +1228,7 @@ Use a volume key stored in a file. endif::[] ifdef::ACTION_FORMAT[] This allows creating a LUKS header with this specific volume key. -If the volume key was taken from an existing LUKS header and all other parameters are the same, then the new header decrypts the data encrypted with the header the volume key was taken from. +If the volume key was taken from an existing LUKS header and all other parameters are the same, then the new header decrypts the data encrypted with the header from which the volume key was taken. + endif::[] ifdef::ACTION_LUKSDUMP,ACTION_BITLKDUMP[] @@ -1237,19 +1236,19 @@ The volume key is stored in a file instead of being printed out to standard outp + endif::[] ifdef::ACTION_LUKSADDKEY[] -This allows adding a new keyslot without having to know passphrase to existing one. -It may be also used when no keyslot is active. +This allows adding a new keyslot without having to know the passphrase to the existing one. +It may also be used when no keyslot is active. + endif::[] ifdef::ACTION_OPEN[] This allows one to open _luks_ and _bitlk_ device types without giving a passphrase. + -For devices in reencryption the option may be used twice to specify both old and new volume keys. -When using the option twice make sure you pair each --volume-key-file option with respective --key-size parameter as well. +For devices in reencryption, the option may be used twice to specify both old and new volume keys. +When using the option twice, make sure you pair each --volume-key-file option with the respective --key-size parameter as well. endif::[] ifdef::ACTION_REENCRYPT[] *LUKS2*: -Provides current volume key stored in a file. +Provides the current volume key stored in a file. It can be used to reencrypt the device with no active keyslot together with --new-volume-key-file or --new-volume-key-keyring options. + *LUKS1*: @@ -1258,7 +1257,7 @@ See --new-volume-key-file. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY[] *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. +Otherwise, you can end up with a low-entropy or otherwise partially predictable volume key, which will compromise security. endif::[] endif::[] @@ -1267,20 +1266,20 @@ ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[] Use a volume key stored in a keyring. This allows one to open _luks_ and _plain_ device types without giving a passphrase. + -For LUKS, the key and associated type has to be readable from userspace so that volume key digest may be verified in before activation. -For devices in reencryption the option may be used twice to specify both old and new volume keys. +For LUKS, the key and associated type have to be readable from userspace so that the volume key digest may be verified before activation. +For devices in reencryption, the option may be used twice to specify both old and new volume keys. + For PLAIN type, the user must ensure that the key in the keyring is unchanged since activation. Otherwise, reloading the key can cause data corruption after an unexpected key change. + The __ uses keyctl-compatible syntax. This can either be a numeric key ID or a string name in the format _%:_. -See also *KEY IDENTIFIERS* section of *keyctl*(1). -When no _%:_ prefix is specified we assume the key type is _user_ (default type). +See also the *KEY IDENTIFIERS* section of *keyctl*(1). +When no _%:_ prefix is specified, we assume the key type is _user_ (default type). endif::[] ifdef::ACTION_REENCRYPT[] *--write-log* (LUKS1 only):: -Update log file after every block write. -This can slow down reencryption but will minimize data loss in the case of system crash. +Update the log file after every block is written. +This can slow down reencryption, but it will minimize data loss in the case of a system crash. endif::[] diff --git a/man/cryptsetup-benchmark.8.adoc b/man/cryptsetup-benchmark.8.adoc index 05f317e9..31e3ace8 100644 --- a/man/cryptsetup-benchmark.8.adoc +++ b/man/cryptsetup-benchmark.8.adoc @@ -16,18 +16,18 @@ cryptsetup-benchmark - benchmarks ciphers and KDF == DESCRIPTION -Benchmarks ciphers and KDF (key derivation function). -Without parameters, it tries to measure few common configurations. +Benchmarks, ciphers and KDF (key derivation function). +Without parameters, it tries to measure a few common configurations. -To benchmark other ciphers or modes, you need to specify --cipher and --key-size options. +To benchmark other ciphers or modes, specify --cipher and --key-size options. To benchmark PBKDF you need to specify --pbkdf or --hash with optional cost parameters --iter-time, --pbkdf-memory or --pbkdf-parallel. *NOTE:* This benchmark uses memory only and is only informative. You cannot directly predict real storage encryption speed from it. -For testing block ciphers, this benchmark requires kernel userspace crypto API to be available (introduced in Linux kernel 2.6.38). -If you are configuring kernel yourself, enable "User-space interface for symmetric key cipher algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option). +For testing block ciphers, this benchmark requires the kernel userspace crypto API to be available (introduced in Linux kernel 2.6.38). +If you are configuring the kernel yourself, enable "User-space interface for symmetric key cipher algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option). ** can be [--cipher, --key-size, --hash, --pbkdf, --iter-time, --pbkdf-memory, --pbkdf-parallel]. diff --git a/man/cryptsetup-bitlkDump.8.adoc b/man/cryptsetup-bitlkDump.8.adoc index 8fe6ab53..d54abf0f 100644 --- a/man/cryptsetup-bitlkDump.8.adoc +++ b/man/cryptsetup-bitlkDump.8.adoc @@ -19,7 +19,7 @@ cryptsetup-bitlkDump - dump the header information of a BITLK (BitLocker compati Dump the header information of a BITLK (BitLocker compatible) device. If the --dump-volume-key option is used, the BITLK device volume key is dumped instead of header information. -You have to provide password or keyfile to dump volume key. +You have to provide a password or keyfile to dump the volume key. Beware that the volume key can be used to decrypt the data stored in the container without a passphrase. This means that if the volume key is compromised, the whole device has to be erased to prevent further access. diff --git a/man/cryptsetup-close.8.adoc b/man/cryptsetup-close.8.adoc index 2417a190..443c3d70 100644 --- a/man/cryptsetup-close.8.adoc +++ b/man/cryptsetup-close.8.adoc @@ -18,7 +18,7 @@ cryptsetup-close - removes the existing mapping (and the associated key) Removes the existing mapping and wipes the key from kernel memory. -For backward compatibility, there are *close* command aliases: *remove*, *plainClose*, *luksClose*, *loopaesClose*, *tcryptClose*, *bitlkClose* (all behave exactly the same, device type is determined automatically from the active device). +For backward compatibility, there are *close* command aliases: *remove*, *plainClose*, *luksClose*, *loopaesClose*, *tcryptClose*, *bitlkClose* (all behave the same, device type is determined automatically from the active device). ** can be [--deferred, --cancel-deferred, --header, --disable-locks]. diff --git a/man/cryptsetup-convert.8.adoc b/man/cryptsetup-convert.8.adoc index 4d49cc27..bd320420 100644 --- a/man/cryptsetup-convert.8.adoc +++ b/man/cryptsetup-convert.8.adoc @@ -17,15 +17,15 @@ cryptsetup-convert - converts the device between LUKS1 and LUKS2 format == DESCRIPTION Converts the device between LUKS1 and LUKS2 format (if possible). -The conversion will not be performed if there is an additional LUKS2 feature or LUKS1 has unsupported header size. +The conversion will not be performed if there is an additional LUKS2 feature or LUKS1 has an unsupported header size. For conversion from LUKS2 to LUKS1, all active keyslots must use the PBKDF2 key-derivation function. The PBKDF2 and anti-forensic filter (AF) hash must be the same as the hash used in the digest. All keyslot numbers must be lower than 8 (LUKS1 maximum slot number). There must be at least one active keyslot and no unbound or reencryption keyslots. -Conversion (both directions) must be performed on inactive device. -There must not be active dm-crypt mapping established for LUKS header requested for conversion. +Conversion (both directions) must be performed on an inactive device. +There must not be an active dm-crypt mapping established for the LUKS header requested for conversion. The *--type* option is mandatory with the following accepted values: _luks1_ or _luks2_. diff --git a/man/cryptsetup-erase.8.adoc b/man/cryptsetup-erase.8.adoc index 3687241a..7caf9889 100644 --- a/man/cryptsetup-erase.8.adoc +++ b/man/cryptsetup-erase.8.adoc @@ -18,11 +18,11 @@ cryptsetup-erase, cryptsetup-luksErase - erase all keyslots == DESCRIPTION Erase all keyslots and make the LUKS container permanently inaccessible. -Unless the device is configured with HW OPAL support you do not need to provide any password for this operation. +Unless the device is configured with HW OPAL support, you do not need to provide any password for this operation. *WARNING:* This operation is irreversible. -*WARNING:* with --hw-opal-factory-reset ALL data is lost on the device, regardless of the partition it is ran on, if any, and regardless of any LUKS2 header backup, and does not require a valid LUKS2 header to be present on the device to run. +*WARNING:* with --hw-opal-factory-reset ALL data is lost on the device, regardless of the partition it is run on, if any, and regardless of any LUKS2 header backup, and does not require a valid LUKS2 header to be present on the device to run. ** can be [--header, --disable-locks, --hw-opal-factory-reset, --key-file]. diff --git a/man/cryptsetup-fvault2Dump.8.adoc b/man/cryptsetup-fvault2Dump.8.adoc index 5801f0f0..b2b911f6 100644 --- a/man/cryptsetup-fvault2Dump.8.adoc +++ b/man/cryptsetup-fvault2Dump.8.adoc @@ -19,7 +19,7 @@ cryptsetup-fvault2Dump - dump the header information of a FVAULT2 (FileVault2 co Dump the header information of a FVAULT2 (FileVault2 compatible) device. If the --dump-volume-key option is used, the FVAULT2 device volume key is dumped instead of header information. -You have to provide password or keyfile to dump volume key. +You have to provide a password or keyfile to dump the volume key. Beware that the volume key can be used to decrypt the data stored in the container without a passphrase. This means that if the volume key is compromised, the whole device has to be erased to prevent further access. diff --git a/man/cryptsetup-isLuks.8.adoc b/man/cryptsetup-isLuks.8.adoc index aac559c8..22bd5d6e 100644 --- a/man/cryptsetup-isLuks.8.adoc +++ b/man/cryptsetup-isLuks.8.adoc @@ -16,12 +16,12 @@ cryptsetup-isLuks - check if a device is a LUKS device == DESCRIPTION -Returns true, if is a LUKS device, false otherwise. +Returns true if is a LUKS device, false otherwise. Use option -v to get human-readable feedback. 'Command successful.' means the device is a LUKS device. -By specifying --type you may query for specific LUKS version. +By specifying --type, you may query for a specific LUKS version. ** can be [--header, --type, --disable-locks]. diff --git a/man/cryptsetup-luksAddKey.8.adoc b/man/cryptsetup-luksAddKey.8.adoc index a72f0f4d..86f08192 100644 --- a/man/cryptsetup-luksAddKey.8.adoc +++ b/man/cryptsetup-luksAddKey.8.adoc @@ -18,16 +18,16 @@ cryptsetup-luksAddKey - add a new passphrase 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 or --volume-key-keyring). +Alternatively to the existing passphrase, the user may pass directly the volume key (via --volume-key-file or --volume-key-keyring). 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. +If you don't pass a new key via --volume-key-file option, a new random key is generated. +The 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. +*NOTE:* Some parameters are effective only if used with the LUKS2 format that supports per-keyslot parameters. +For LUKS1, the PBKDF type and hash algorithm are always the same for all keyslots. ** can be [--key-file, --keyfile-offset, --keyfile-size, --new-keyfile, --new-keyfile-offset, --new-keyfile-size, --key-slot, --new-key-slot, --volume-key-file, --volume-key-keyring, --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, --external-tokens-path]. @@ -35,13 +35,13 @@ include::man/common_options.adoc[] == EXAMPLES -*NOTE*: When not specified otherwise interactive passphrase prompt is always default method. +*NOTE*: The interactive passphrase prompt is always the default method when not specified otherwise. -Add new keyslot using interactive passphrase prompt for both existing and new passphrase: +Add new keyslot using interactive passphrase prompt for both existing and new passphrases: *cryptsetup luksAddKey /dev/device* -Add new keyslot using LUKS2 tokens to unlock existing keyslot with interactive passphrase prompt for new passphrase: +Add a new keyslot using LUKS2 tokens to unlock the existing keyslot with an interactive passphrase prompt for the new passphrase: *cryptsetup luksAddKey --token-only /dev/device* diff --git a/man/cryptsetup-luksChangeKey.8.adoc b/man/cryptsetup-luksChangeKey.8.adoc index d30a3c40..ca4e3da6 100644 --- a/man/cryptsetup-luksChangeKey.8.adoc +++ b/man/cryptsetup-luksChangeKey.8.adoc @@ -20,17 +20,17 @@ 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. +If a keyslot is specified (via --key-slot), the passphrase for that keyslot must be given, and the new passphrase will overwrite the specified keyslot. +If no keyslot is specified and there is still a free keyslot, then the new passphrase will be put into a free keyslot before the keyslot containing the old passphrase is purged. +If there is no free keyslot, then the keyslot 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. -LUKS2 mitigates that by never overwriting existing keyslot area as long as there's a free space in keyslots area at least for one more LUKS2 keyslot. +*WARNING:* If a keyslot is overwritten, a media failure during this operation can cause the overwrite to fail after the old passphrase has been wiped, making the LUKS container inaccessible. +LUKS2 mitigates that by never overwriting the existing keyslot area as long as there's a free space in the keyslots area at least for one more LUKS2 keyslot. -*WARNING:* If you need to use both luksChangeKey and reencrypt (e.g. to recover from a leak) you need to use them in that order to not leak the new volume key. +*WARNING:* If you need to use both luksChangeKey and reencrypt (e.g., to recover from a leak), you need to use them in that order to avoid leaking the new volume key. -*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. +*NOTE:* Some parameters are effective only if used with the LUKS2 format that supports per-keyslot parameters. +For LUKS1, the PBKDF type and hash algorithm are always the same for all keyslots. ** 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]. diff --git a/man/cryptsetup-luksConvertKey.8.adoc b/man/cryptsetup-luksConvertKey.8.adoc index 6a8d0893..705c73a6 100644 --- a/man/cryptsetup-luksConvertKey.8.adoc +++ b/man/cryptsetup-luksConvertKey.8.adoc @@ -17,14 +17,14 @@ cryptsetup-luksConvertKey - converts an existing LUKS2 keyslot to new PBKDF para == 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. +The passphrase for the 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. +If no keyslot is specified and there is still a free keyslot, 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, the keyslot with the old parameters is directly overwritten. -*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. +*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, making the LUKS container inaccessible. ** 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]. diff --git a/man/cryptsetup-luksDump.8.adoc b/man/cryptsetup-luksDump.8.adoc index 46edc986..bae441b5 100644 --- a/man/cryptsetup-luksDump.8.adoc +++ b/man/cryptsetup-luksDump.8.adoc @@ -19,17 +19,17 @@ cryptsetup-luksDump - dump the header information of a LUKS device 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. +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. +A passphrase must be supplied to dump the volume key, 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. +To dump an unbound key (LUKS2 format only), --unbound parameter, specific --key-slot id and proper passphrase must be supplied, 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. +To dump LUKS2 JSON metadata (without basic header information like UUID), use --dump-json-metadata option. ** 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, --external-tokens-path]. diff --git a/man/cryptsetup-luksFormat.8.adoc b/man/cryptsetup-luksFormat.8.adoc index cd050bc9..7fe1317a 100644 --- a/man/cryptsetup-luksFormat.8.adoc +++ b/man/cryptsetup-luksFormat.8.adoc @@ -16,14 +16,14 @@ cryptsetup-luksFormat - initialize a LUKS partition and set the initial passphra == DESCRIPTION -Initializes a LUKS partition and sets the initial passphrase (for key-slot 0), either via prompting or via . -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. +Initializes a LUKS partition and sets the initial passphrase (for keyslot 0) via prompting or . +Note that if the second argument is present, the passphrase is taken from the file given there, without using the --key-file option. +Also note that for both forms of reading the passphrase from a file, you can give '-' as a 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. +You cannot call luksFormat on a device or filesystem that is mapped or in use, e.g., a mounted filesystem, used in LVM, active RAID member, etc. +The device or filesystem has to be unmounted in order to call luksFormat. -To use specific version of LUKS format, use _--type luks1_ or _type luks2_. +To use a specific version of LUKS format, use _--type luks1_ or _type luks2_. To use OPAL hardware encryption on a self-encrypting drive, use --hw-opal or --hw-opal-only. Note that some OPAL drives can require a PSID reset (with deletion of data) before using the LUKS format with OPAL options. diff --git a/man/cryptsetup-luksHeaderBackup.8.adoc b/man/cryptsetup-luksHeaderBackup.8.adoc index 24855279..d31adb82 100644 --- a/man/cryptsetup-luksHeaderBackup.8.adoc +++ b/man/cryptsetup-luksHeaderBackup.8.adoc @@ -17,14 +17,13 @@ cryptsetup-luksHeaderBackup - store a binary backup of the LUKS header and keysl == DESCRIPTION Stores a binary backup of the LUKS header and keyslot area. + -*NOTE:* Using '-' as filename writes the header backup to a file named -'-'. +*NOTE:* Using '-' as a filename writes the header backup to a file named '-'. ** 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. +*WARNING:* This backup file and a passphrase valid at the time of backup allow 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 wipe the LUKS device securely by just overwriting the header and keyslots. +You must either securely erase all header backups or overwrite the encrypted data area. The second option is less secure, as some sectors can survive, e.g., due to defect management. include::man/common_options.adoc[] diff --git a/man/cryptsetup-luksHeaderRestore.8.adoc b/man/cryptsetup-luksHeaderRestore.8.adoc index 28b5b8db..59d06f0e 100644 --- a/man/cryptsetup-luksHeaderRestore.8.adoc +++ b/man/cryptsetup-luksHeaderRestore.8.adoc @@ -17,14 +17,14 @@ cryptsetup-luksHeaderRestore - restore a binary backup of the LUKS header and ke == 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 '-'. +*NOTE:* Using '-' as a filename reads the header backup from a file named '-'. ** can be [--header, --header-backup-file, --disable-locks]. -*WARNING:* Header and keyslots will be replaced, only the passphrases from the backup will work afterward. +*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. +This command requires that the volume key size and data offset of the LUKS header already on the device and the header backup match. +Alternatively, the backup will also be written if there is no LUKS header on the device. include::man/common_options.adoc[] include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksKillSlot.8.adoc b/man/cryptsetup-luksKillSlot.8.adoc index fdafb176..ef1778bc 100644 --- a/man/cryptsetup-luksKillSlot.8.adoc +++ b/man/cryptsetup-luksKillSlot.8.adoc @@ -8,17 +8,17 @@ == Name -cryptsetup-luksKillSlot - wipe a key-slot from the LUKS device +cryptsetup-luksKillSlot - wipe a keyslot from the LUKS device == SYNOPSIS -*cryptsetup _luksKillSlot_ [] * +*cryptsetup _luksKillSlot_ [] * == DESCRIPTION -Wipe the key-slot number 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. +Wipe the keyslot with the number 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 keyslot, but requires an interactive confirmation when doing so. Removing the last passphrase makes a LUKS container permanently inaccessible. ** can be [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type, --verify-passphrase, --timeout]. @@ -26,7 +26,7 @@ Removing the last passphrase makes a LUKS container permanently inaccessible. *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. +*NOTE:* If no passphrase is provided (on stdin or through --key-file argument) and batch-mode (-q) is active, the keyslot is removed without any other warning. include::man/common_options.adoc[] include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksSuspend.8.adoc b/man/cryptsetup-luksSuspend.8.adoc index 1e869e37..22a2d05a 100644 --- a/man/cryptsetup-luksSuspend.8.adoc +++ b/man/cryptsetup-luksSuspend.8.adoc @@ -21,7 +21,7 @@ Needs kernel 2.6.19 or later. While the _luksSuspend_ operation wipes encryption keys from memory, it does not remove possible plaintext data in various caches or in-kernel metadata for mounted filesystems. -After this operation, you have to use _luksResume_ to reinstate the encryption key and unblock the device or _close_ to remove the mapped device. +After this operation, you must use _luksResume_ to reinstate the encryption key and unblock the device or _close_ to remove the mapped device. ** can be [--header, --disable-locks]. diff --git a/man/cryptsetup-open.8.adoc b/man/cryptsetup-open.8.adoc index 997996ec..83596bea 100644 --- a/man/cryptsetup-open.8.adoc +++ b/man/cryptsetup-open.8.adoc @@ -19,7 +19,7 @@ Opens (creates a mapping with) backed by device . Device type can be _plain_, _luks_ (default), _luks1_, _luks2_, _loopaes_ or _tcrypt_. -For backward compatibility there are *open* command aliases: +For backward compatibility, there are *open* command aliases: *create* (argument-order ): open --type plain + *plainOpen*: open --type plain + @@ -28,8 +28,8 @@ For backward compatibility there are *open* command aliases: *tcryptOpen*: open --type tcrypt + *bitlkOpen*: open --type bitlk -** are type specific and are described below for individual device types. -For *create*, the order of the and options is inverted for historical reasons, all other aliases use the standard * * order. +** are type-specific and are described below for individual device types. +For *create*, the order of the and options is inverted for historical reasons; all other aliases use the standard * * order. === PLAIN *open --type plain * --cipher --key-size --hash + @@ -38,10 +38,10 @@ create (OBSOLETE syntax) Opens (creates a mapping with) backed by device . -*WARNING:* You should always specify options --cipher, --key-size and (if no keyfile or keyring is used) then also --hash to avoid incompatibility as default values can be different in older cryptsetup versions. + +*WARNING:* You should always specify options --cipher, --key-size and (if no keyfile or keyring is used) then also --hash to avoid incompatibility, as default values can differ in older cryptsetup versions. + The plain format also allows retrieving a volume key from a kernel keyring specified by --volume-key-keyring. -Key in kernel keyring must be configured before issuing cryptsetup commands, as cryptsetup does not upload any keys to the keyring in plain mode. +The key in the kernel keyring must be configured before issuing cryptsetup commands, as cryptsetup does not upload any keys to the keyring in plain mode. For subsequent commands (like resize), the user must ensure that the key in the keyring is unchanged. Otherwise, reloading the key can cause data corruption after an unexpected key change. @@ -55,7 +55,7 @@ To map the encrypted device /dev/sda10 to the decrypted device /dev/mapper/e1, y The decrypted device can then be used as a normal block device to mount a filesystem. -To map a device with a volume key in the preconfigured trusted or encrypted keyring, you need to specify keyring with the key and remove hash specification, for example, to use *%trusted:mykey*: +To map a device with a volume key in the preconfigured trusted or encrypted keyring, you need to specify the keyring with the key and remove the hash specification, for example, to use *%trusted:mykey*: *cryptsetup open --type plain /dev/sda10 e1 --volume-key-keyring=%trusted:mykey --cipher aes-xts-plain64 --key-size 256* @@ -69,10 +69,10 @@ luksOpen (old syntax) Opens the LUKS device and sets up a mapping after successful verification of the supplied passphrase. First, the passphrase is searched in LUKS2 tokens unprotected by PIN. -If such token does not exist (or fails to unlock keyslot) and also the passphrase is not supplied via --key-file, the command prompts for passphrase interactively. +If such a token does not exist (or fails to unlock keyslot) and the passphrase is not supplied via --key-file, the command prompts for passphrase interactively. -If there is 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. +If there is a valid LUKS2 token but it requires a PIN to unlock the assigned keyslot, it is not used unless one of the following options is added: --token-only, +--token-type where type matches the desired PIN-protected token or --token-id with id matching the PIN-protected token. ** can be [--key-file, --keyfile-offset, --keyfile-size, --readonly, --test-passphrase, --allow-discards, --header, --key-slot, --volume-key-file, --token-id, --token-only, --token-type, --disable-external-tokens, --disable-keyring, --disable-locks, --type, --refresh, --serialize-memory-hard-pbkdf, --unbound, --tries, --timeout, --verify-passphrase, --persistent, --volume-key-keyring, --link-vk-to-keyring, --external-tokens-path]. @@ -86,17 +86,17 @@ If the key file is encrypted with GnuPG, then you have to use --key-file=- and d gpg --decrypt | cryptsetup loopaesOpen --key-file=- -*WARNING:* The loop-AES extension cannot use the direct input of the key file on the real terminal because the keys are separated by end-of-line and only part of the multi-key file would be read. + +*WARNING:* The loop-AES extension cannot use the direct input of the key file on the real terminal because the keys are separated by end-of-line, and only part of the multi-key file would be read. + If you need it in script, just use the pipe redirection: + echo $keyfile | cryptsetup loopaesOpen --key-file=- Use --keyfile-size to specify the proper key length if needed. Use --offset to specify device offset. -Note that the units need to be specified in number of 512 byte sectors. +Note that the units need to be specified in terms of 512-byte sectors. Use --skip to specify the IV offset. -If the original device used an offset and but did not use it in IV sector calculations, you have to explicitly use --skip 0 in addition to the offset parameter. +If the original device used an offset but did not use it in IV sector calculations, you must explicitly use --skip 0 in addition to the offset parameter. Use --hash to override the default hash function for passphrase hashing (otherwise it is detected according to key size). @@ -111,16 +111,16 @@ up a mapping . ** can be [--key-file, --tcrypt-hidden, --tcrypt-system, --tcrypt-backup, --readonly, --test-passphrase, --allow-discards, --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim, --veracrypt-query-pim, --header, --cipher, --hash, --tries, --timeout, --verify-passphrase]. -The keyfile parameter allows a combination of file content with the passphrase and can be repeated. -Note that using keyfiles is compatible with TCRYPT and is different from LUKS keyfile logic. +The keyfile parameter allows a combination of file content with the passphrase, which can be repeated. +Note that using keyfiles is compatible with TCRYPT and differs from LUKS keyfile logic. If --cipher or --hash options are used, only cipher chains or PBKDF2 variants with the specified hash algorithms are checked. -This could speed up unlocking the device (but also it reveals some information about the container). +This could speed up unlocking the device (but also reveals some information about the container). -If you use --header in combination with hidden or system options, the header file must contain specific headers on the same positions as the original encrypted container. +If you use --header in combination with hidden or system options, the header file must contain specific headers in the same positions as the original encrypted container. *WARNING:* Option --allow-discards cannot be combined with option --tcrypt-hidden. -For normal mapping, it can cause the destruction of hidden volume (hidden volume appears as unused space for outer volume so this space can be discarded). +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 * + @@ -130,8 +130,8 @@ Opens the BITLK (a BitLocker compatible) and sets up a mapping . ** can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase]. -Note that --test-passphrase doesn't work with --volume-key-file because we cannot check whether the provided volume key is correct for this device or not. -When using --volume-key-file the device will be opened even if the provided key is not correct. +Note that --test-passphrase doesn't work with --volume-key-file because we cannot check whether the provided volume key is correct for this device. +When using --volume-key-file, the device will be opened even if the provided key is incorrect. === FileVault2 *open --type fvault2 * + diff --git a/man/cryptsetup-reencrypt.8.adoc b/man/cryptsetup-reencrypt.8.adoc index b8c9cba7..ac8a64ff 100644 --- a/man/cryptsetup-reencrypt.8.adoc +++ b/man/cryptsetup-reencrypt.8.adoc @@ -26,17 +26,17 @@ There are 3 basic modes of operation: or --active-name (LUKS2 only) is mandatory parameter. -Cryptsetup _reencrypt_ action can be used to change reencryption parameters which otherwise require full on-disk data change (re-encryption). -The _reencrypt_ action reencrypts data on LUKS device in-place. +Cryptsetup _reencrypt_ action can be used to change reencryption parameters, which otherwise require full on-disk data change (re-encryption). +The _reencrypt_ action reencrypts data on the LUKS device in-place. You can regenerate *volume key* (the real key used in on-disk encryption unlocked by passphrase), *cipher*, *cipher mode* or *encryption sector size* (LUKS2 only). -*WARNING:* If you need to use both luksChangeKey and reencrypt (e.g. to recover from a leak) you need to use them in that order to not leak the new volume key. +*WARNING:* If you need to use both luksChangeKey and reencrypt (e.g., to recover from a leak), you need to use them in that order to avoid leaking the new volume key. -Reencryption process may be safely interrupted by a user via SIGINT signal (ctrl+c). -Same applies to SIGTERM signal (i.e. issued by systemd during system shutdown). +The reencryption process may be safely interrupted by a user via SIGINT signal (ctrl+c). +The same applies to the SIGTERM signal (i.e., issued by systemd during system shutdown). -For in-place encryption mode, the _reencrypt_ action additionally takes all options available for _luksFormat_ action for respective LUKS version (see cryptsetup-luksFormat man page for more details). +For in-place encryption mode, the _reencrypt_ action additionally takes all options available for the _luksFormat_ action for the respective LUKS version (see cryptsetup-luksFormat man page for more details). See *cryptsetup-luksFormat*(8). *NOTE* that for encrypt and decrypt mode, the whole device must be treated as unencrypted -- there are no guarantees of confidentiality as part of the device contains plaintext. @@ -88,22 +88,22 @@ See *cryptsetup-luksFormat*(8). == LUKS2 REENCRYPTION -With parameter cryptsetup looks up active dm mapping. -If no active mapping is detected, it starts offline LUKS2 reencryption otherwise online reencryption takes place. +With the parameter, cryptsetup looks up the active dm mapping. +If no active mapping is detected, it starts offline LUKS2 reencryption; otherwise, online reencryption occurs. To resume already initialized or interrupted reencryption, just run the cryptsetup _reencrypt_ command again to continue the reencryption operation. Reencryption may be resumed with different --resilience or --hotzone-size unless implicit datashift resilience mode is used: either encrypt mode with --reduce-device-size option or decrypt mode with original LUKS2 header exported in --header file. -If the reencryption process was interrupted abruptly (reencryption process crash, system crash, poweroff) it may require recovery. -The recovery is currently run automatically on next activation (action _open_) when needed or explicitly by user (action _repair_). +If the reencryption process was interrupted abruptly (reencryption process crash, system crash, or power off), it may require recovery. +The recovery is run automatically on next activation (action _open_) when needed or explicitly by the user (action _repair_). -Optional parameter takes effect only with encrypt option and it activates device immediately after encryption initialization gets finished. -That's useful when device needs to be ready as soon as possible and mounted (used) before full data area encryption is completed. +The optional parameter takes effect only with the encrypt option, and it activates device immediately after encryption initialization is finished. +That's useful when the device needs to be ready as soon as possible and mounted (used) before full data area encryption is completed. == LUKS1 REENCRYPTION -Current working directory must be writable and temporary files created during reencryption must be present. -During reencryption process the LUKS1 device is marked unavailable and must be offline (no dm-crypt mapping or mounted filesystem). +The current working directory must be writable, and temporary files created during reencryption must be present. +During reencryption, the LUKS1 device is marked unavailable and must be offline (no dm-crypt mapping or mounted filesystem). *WARNING*: The LUKS1 reencryption code is not resistant to hardware or kernel failures during reencryption (you can lose your data in this case). @@ -116,17 +116,17 @@ include::man/common_options.adoc[] === LUKS2 ENCRYPTION EXAMPLES Encrypt LUKS2 device (in-place). -Make sure last 32 MiB on _/dev/plaintext_ is unused (e.g.: does not contain filesystem data): +Make sure the last 32 MiB on _/dev/plaintext_ is unused (e.g., does not contain filesystem data): *cryptsetup reencrypt --encrypt --type luks2 --reduce-device-size 32m /dev/plaintext_device* Encrypt LUKS2 device (in-place). Only the initial 1 GiB of original _/dev/plaintext_ data is encrypted while being shifted backwards. -Make sure last 32 MiB (tail) on the data device is unused (e.g.: does not contain any data): +Make sure the last 32 MiB (tail) on the data device is unused (e.g., does not contain any data): *cryptsetup reencrypt --encrypt --type luks2 --device-size 1g --reduce-device-size 32m /dev/plaintext_device* -Encrypt LUKS2 device (in-place) with detached header put in a file: +Encrypt LUKS2 device (in-place) with detached header, put in a file: *cryptsetup reencrypt --encrypt --type luks2 --header my_luks2_header /dev/plaintext_device* @@ -134,7 +134,7 @@ Initialize LUKS2 in-place encryption operation only and activate the device (not *cryptsetup reencrypt --encrypt --type luks2 --init-only --reduce-device-size 32m /dev/plaintext_device my_future_luks_device* -Resume online encryption on device initialized in example above: +Resume online encryption on the device initialized in the example above: *cryptsetup reencrypt --resume-only /dev/plaintext_device* or *cryptsetup reencrypt --active-name my_future_luks_device* @@ -145,19 +145,19 @@ Reencrypt LUKS2 device (refresh volume key only): *cryptsetup reencrypt /dev/encrypted_device* -Reencrypt LUKS2 device using keyslot(s) associated to the token 3. +Reencrypt LUKS2 device using keyslot(s) associated with the token 3. All other keyslots will be removed after the reencryption finishes. *cryptsetup reencrypt --token-id 3 /dev/encrypted_device* -Reencrypt LUKS2 device using keyslots associated to all 'systemd-tpm2' tokens. +Reencrypt LUKS2 device using keyslots associated with all 'systemd-tpm2' tokens. All other keyslots will be removed after the reencryption finishes. *cryptsetup reencrypt --token-type systemd-tpm2 /dev/encrypted_device* === LUKS2 DECRYPTION EXAMPLES -Decrypt LUKS2 device with header put in head of data device (header file does not exist): +Decrypt LUKS2 device with header put in the head of the data device (header file does not exist): *cryptsetup reencrypt --decrypt --header /export/header/to/file /dev/encrypted_device* diff --git a/man/cryptsetup-refresh.8.adoc b/man/cryptsetup-refresh.8.adoc index a09d5349..de88669f 100644 --- a/man/cryptsetup-refresh.8.adoc +++ b/man/cryptsetup-refresh.8.adoc @@ -18,14 +18,14 @@ cryptsetup-refresh - refresh parameters of an active mapping Refreshes parameters of active mapping . -Updates parameters of active device without the need to deactivate the device (and umount filesystem). -Currently, it supports parameters refresh on following devices: LUKS1, LUKS2 (including authenticated encryption), plain crypt and loop-AES. +Update parameters of active device without the need to deactivate the device (and unmount the filesystem). +Currently, it supports parameter refresh on the following devices: LUKS1, LUKS2 (including authenticated encryption), plain crypt and loop-AES. Mandatory parameters are identical to those of an open action for the respective device type. -You may change following parameters on all devices --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue and --allow-discards. +You may change the following parameters on all devices --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue and --allow-discards. -Refreshing the device without any optional parameter will refresh the device with default setting (respective to device type). +Refreshing the device without any optional parameter will refresh the device with the default setting (respective to device type). *LUKS2 only:* @@ -33,7 +33,7 @@ The --integrity-no-journal parameter affects only LUKS2 devices with the underly Adding option --persistent stores any combination of device parameters above in LUKS2 metadata (only after successful refresh operation). -The --disable-keyring parameter refreshes a device with volume key passed in dm-crypt driver. +The --disable-keyring parameter refreshes a device with the volume key passed in the dm-crypt driver. ** can be [--allow-discards, --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue, --header, --disable-keyring, --disable-locks, --persistent, --integrity-no-journal]. diff --git a/man/cryptsetup-repair.8.adoc b/man/cryptsetup-repair.8.adoc index 2f629629..9e75de13 100644 --- a/man/cryptsetup-repair.8.adoc +++ b/man/cryptsetup-repair.8.adoc @@ -19,21 +19,21 @@ cryptsetup-repair - repair the device metadata Tries to repair the device metadata if possible. Currently supported only for LUKS device type. -This command is useful to fix some known benign LUKS metadata header corruptions. +This command is useful for fixing some known benign LUKS metadata header corruptions. Only basic corruptions of unused keyslot are fixable. -This command will only change the LUKS header, not any key-slot data. +This command will only change the LUKS header, not any keyslot data. You may enforce LUKS version by adding --type option. It also repairs (upgrades) LUKS2 reencryption metadata by adding a metadata digest that protects it against malicious changes. -If LUKS2 reencryption was interrupted in the middle of writing reencryption segment the repair command can be used to perform reencryption recovery so that reencryption can continue later. -Repairing reencryption requires verification of reencryption keyslot so passphrase or keyfile is needed. +If LUKS2 reencryption was interrupted while writing the reencryption segment, the repair command can perform reencryption recovery so that reencryption can continue later. +Repairing reencryption requires verification of the reencryption keyslot, so a passphrase or keyfile is needed. === LUKS keyslots corruption detection The repair command also checks for detectable corruption of keyslot content. -Corruption of a keyslot results in a situation when a known password is no longer accepted. -It can happen due to storage media failure or overwriting the keyslot area by some other data. +Corruption of a keyslot results in a situation where a known password is no longer accepted. +It can happen due to storage media failure or overwriting the keyslot area with other data. Only certain corruptions, usually only a low-entropy area (like zeroed blocks), can be detected. The detection prints only warnings. @@ -42,7 +42,7 @@ It can also print more specific offsets on the device for detailed manual inspec Please note that the warning can be a false positive (no real corruption happened). Conversely, if the keyslot is corrupted, no recovery is possible. -You have to use LUKS header backup. +You have to use the LUKS header backup. ** can be [--timeout, --verify-passphrase, --disable-locks, --type, --header, --key-file, --keyfile-size, --keyfile-offset, --key-slot]. diff --git a/man/cryptsetup-resize.8.adoc b/man/cryptsetup-resize.8.adoc index 63b542d5..636c9803 100644 --- a/man/cryptsetup-resize.8.adoc +++ b/man/cryptsetup-resize.8.adoc @@ -18,13 +18,13 @@ cryptsetup-resize - resize an active mapping Resizes an active mapping . -If --size (in 512-bytes sectors) or --device-size are not specified, the size is computed from the underlying device. -For LUKS it is the size of the underlying device without the area reserved for LUKS header (see data payload offset in *luksDump* command). -For plain crypt device, the whole device size is used. +If --size (in 512-byte sectors) or --device-size is not specified, the size is computed from the underlying device. +For LUKS, it is the size of the underlying device without the area reserved for the LUKS header (see data payload offset in the *luksDump* command). +For a plain crypt device, the whole device size is used. -Note that this does not change the raw device geometry, it just changes how many sectors of the raw device are represented in the mapped device. +Note that this does not change the raw device geometry; it just changes how many sectors of the raw device are represented in the mapped device. -If cryptsetup detected volume key for active device loaded in kernel keyring service, resize action would first try to retrieve the key using a token. +If cryptsetup detected a volume key for the active device loaded in the kernel keyring service, the resize action would first try to retrieve the key using a token. Only if it failed, it'd ask for a passphrase to unlock a keyslot (LUKS) or to derive a volume key again (plain mode). The kernel keyring is used by default for LUKS2 devices. diff --git a/man/cryptsetup-ssh.8.adoc b/man/cryptsetup-ssh.8.adoc index 0e51c2ad..753b603f 100644 --- a/man/cryptsetup-ssh.8.adoc +++ b/man/cryptsetup-ssh.8.adoc @@ -14,10 +14,10 @@ cryptsetup-ssh - manage LUKS2 SSH token == DESCRIPTION -Experimental cryptsetup plugin for unlocking LUKS2 devices with token connected to an SSH server. +Experimental cryptsetup plugin for unlocking LUKS2 devices with a token connected to an SSH server. -This plugin currently allows only adding a token to an existing key slot. -See *cryptsetup(8)* for instructions on how to remove, import or export the token. +This plugin currently allows only adding a token to an existing keyslot. +See *cryptsetup*(8) for instructions on how to remove, import or export the token. === Add operation @@ -25,7 +25,7 @@ See *cryptsetup(8)* for instructions on how to remove, import or export the toke Adds the SSH token to **. -The specified SSH server must contain a key file on the specified path with a passphrase for an existing key slot on the device. +The specified SSH server must contain a key file on the specified path with a passphrase for an existing keyslot on the device. Provided credentials will be used by cryptsetup to get the password when opening the device using the token. Options --ssh-server, --ssh-user, --ssh-keypath and --ssh-path are required for this operation. @@ -43,7 +43,7 @@ Show help *--key-slot* _number_:: Keyslot to assign the token to. -If not specified, the token will be assigned to the first key slot matching provided passphrase. +If not specified, the token will be assigned to the first keyslot matching the provided passphrase. *--ssh-keypath* _string_:: Path to the SSH key for connecting to the remote server. @@ -55,7 +55,7 @@ Path to the key file on the remote server. IP address/URL of the remote server for this token. *--ssh-user* _string_:: -Username used for the remote server. +The username used for the remote server. *--verbose*, *-v*:: Shows more detailed error messages diff --git a/man/cryptsetup-tcryptDump.8.adoc b/man/cryptsetup-tcryptDump.8.adoc index 9346c429..0e6d9c94 100644 --- a/man/cryptsetup-tcryptDump.8.adoc +++ b/man/cryptsetup-tcryptDump.8.adoc @@ -18,14 +18,14 @@ cryptsetup-tcryptDump - dump the header information of a TCRYPT (TrueCrypt or Ve Dump the header information of a TCRYPT (TrueCrypt or VeraCrypt compatible) device. -If the --dump-volume-key option is used, the TCRYPT device volume key is dumped instead of TCRYPT header info. -Beware that the volume key (or concatenated volume keys if cipher chain is used) can be used to decrypt the data stored in the TCRYPT container without a passphrase. +If the --dump-volume-key option is used, the TCRYPT device volume key is dumped instead of the TCRYPT header info. +Beware that the volume key (or concatenated volume keys if a cipher chain is used) can be used to decrypt the data stored in the TCRYPT container without a passphrase. This means that if the volume key is compromised, the whole device has to be erased to prevent further access. Use this option carefully. ** can be [--dump-volume-key, --key-file, --tcrypt-hidden, --tcrypt-system, --tcrypt-backup, --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim, --veracrypt-query-pim, --cipher, --hash, --header, --verify-passphrase, --timeout]. -The keyfile parameter allows a combination of file content with the passphrase and can be repeated. +The keyfile parameter allows a combination of file content with the passphrase, which can be repeated. include::man/common_options.adoc[] include::man/common_footer.adoc[] diff --git a/man/cryptsetup-token.8.adoc b/man/cryptsetup-token.8.adoc index 5742de7b..9fcc09ed 100644 --- a/man/cryptsetup-token.8.adoc +++ b/man/cryptsetup-token.8.adoc @@ -17,27 +17,27 @@ cryptsetup-token - manage LUKS2 tokens == DESCRIPTION Action _add_ creates a new keyring token to enable auto-activation of the device. -For the auto-activation, the passphrase must be stored in keyring with the specified description. -Usually, the passphrase should be stored in _user_ or _user-session_ keyring. +For the auto-activation, the passphrase must be stored in the keyring with the specified description. +Usually, the passphrase should be stored in the _user_ or _user-session_ keyring. The _token_ command is supported only for LUKS2. -For adding new keyring token, option --key-description is mandatory. -Also, new token is assigned to key slot specified with --key-slot option or to all active key slots in the case --key-slot option is omitted. +For adding a new keyring token, the option --key-description is mandatory. +Also, a new token is assigned to the keyslot specified with --key-slot option or to all active keyslots if the --key-slot option is omitted. -To remove existing token, specify the token ID which should be removed with --token-id option. +To remove an existing token, specify the token ID that should be removed with --token-id option. *WARNING:* The action _token remove_ removes any token type, not just _keyring_ type from token slot specified by --token-id option. -Action _import_ can store arbitrary valid token json in LUKS2 header. -It may be passed via standard input or via file passed in --json-file option. -If you specify --key-slot then successfully imported token is also assigned to the key slot. +Action _import_ can store an arbitrary valid JSON data in the LUKS2 token. +It may be passed via standard input or a file passed in --json-file option. +If you specify --key-slot, a successfully imported token is also assigned to the keyslot. Action _export_ writes requested token JSON to a file passed with --json-file or to standard output. Action _unassign_ removes token binding to specified keyslot. Both token and keyslot must be specified by --token-id and --key-slot parameters. -If --token-id is used with action _add_ or action _import_ and a token with that ID already exists, option --token-replace can be used to replace the existing token. +If --token-id is used with action _add_ or action _import_ and a token with that ID already exists, option --token-replace can replace the existing token. ** can be [--header, --token-id, --key-slot, --key-description, --disable-external-tokens, --disable-locks, --disable-keyring, --json-file, --token-replace, --unbound, --external tokens-path]. diff --git a/man/cryptsetup.8.adoc b/man/cryptsetup.8.adoc index 446084cf..4b3c9620 100644 --- a/man/cryptsetup.8.adoc +++ b/man/cryptsetup.8.adoc @@ -14,14 +14,14 @@ cryptsetup - manage plain dm-crypt, LUKS, and other encrypted volumes == DESCRIPTION -cryptsetup is used to conveniently setup dm-crypt managed device-mapper mappings. +cryptsetup is used to conveniently set up dm-crypt managed device-mapper mappings. These include plain dm-crypt volumes and LUKS volumes. -The difference is that LUKS uses a metadata header and can hence offer more features than plain dm-crypt. +The difference is that LUKS uses a metadata header and can offer more features than plain dm-crypt. On the other hand, the header is visible and vulnerable to damage. -In addition, cryptsetup provides limited support for the use of loop-AES volumes, TrueCrypt, VeraCrypt, BitLocker and FileVault2 compatible volumes, and for hardware-based encryption on OPAL capable drives. +In addition, cryptsetup provides limited support for using loop-AES volumes, TrueCrypt, VeraCrypt, BitLocker and FileVault2 compatible volumes, and hardware-based encryption on OPAL capable drives. -For more information about specific cryptsetup action see *cryptsetup-*(8), where ** is the name of the cryptsetup action. +For more information about a specific cryptsetup action, see *cryptsetup-*(8), where ** is the name of the cryptsetup action. == BASIC ACTIONS @@ -66,7 +66,7 @@ See *cryptsetup-reencrypt*(8). == PLAIN MODE Plain dm-crypt encrypts the device sector-by-sector with a single, non-salted hash of the passphrase. -No checks are performed, no metadata is used. +No checks are performed, and no metadata is used. There is no formatting operation. When the raw device is mapped (opened), the usual device operations can be used on the mapped device, including filesystem creation. Mapped devices usually reside in /dev/mapper/. @@ -83,33 +83,33 @@ See *cryptsetup-open*(8). == LUKS EXTENSION LUKS, the Linux Unified Key Setup, is a standard for disk encryption. -It adds a standardized header at the start of the device, a key-slot area directly behind the header and the bulk data area behind that. +It adds a standardized header at the start of the device, a keyslot area directly behind the header and the bulk data area behind that. The whole set is called a 'LUKS container'. The device that a LUKS container resides on is called a 'LUKS device'. For most purposes, both terms can be used interchangeably. -But note that when the LUKS header is at a nonzero offset in a device, then the device is not a LUKS device anymore, but has a LUKS container stored in it at an offset. +But note that when the LUKS header is at a non-zero offset in a device, then the device is not a LUKS device anymore, but has a LUKS container stored in it at an offset. LUKS can manage multiple passphrases that can be individually revoked or changed and that can be securely scrubbed from persistent media due to the use of anti-forensic stripes. Passphrases are protected against brute-force and dictionary attacks by Password-Based Key Derivation Function (PBKDF). -LUKS2 is a new version of header format that allows additional extensions like different PBKDF algorithm or authenticated encryption. -You can format device with LUKS2 header if you specify *--type luks2* in *luksFormat* command. +LUKS2 is a new version of the header format that allows additional extensions like different PBKDF algorithms or authenticated encryption. +You can format the device with a LUKS2 header if you specify *--type luks2* in the *luksFormat* command. For activation, the format is already recognized automatically. -Each passphrase, also called a *key* in this document, is associated with one of 8 key-slots. +Each passphrase, also called a *key* in this document, is associated with one of 8 keyslots. Key operations that do not specify a slot affect the first slot that matches the supplied passphrase or the first empty slot if a new passphrase is added. The ** parameter can also be specified by a LUKS UUID in the format UUID=. Translation to real device name uses symlinks in /dev/disk/by-uuid directory. -To specify a detached header, the *--header* parameter can be used in all LUKS commands and always takes precedence over the positional ** parameter. +To specify a detached header, the --header parameter can be used in all LUKS commands and always takes precedence over the positional ** parameter. The following are valid LUKS actions: === FORMAT *luksFormat []* -Initializes a LUKS partition and sets the initial passphrase (for key-slot 0). + +Initializes a LUKS partition and sets the initial passphrase (for keyslot 0). + See *cryptsetup-luksFormat*(8). === OPEN @@ -156,9 +156,9 @@ Converts an existing LUKS2 keyslot to new PBKDF parameters. + See *cryptsetup-luksConvertKey*(8). === KILL SLOT -*luksKillSlot * +*luksKillSlot * -Wipe the key-slot number from the LUKS device. + +Wipe the keyslot with the from the LUKS device. + See *cryptsetup-luksKillSlot*(8). === ERASE @@ -218,7 +218,7 @@ See *cryptsetup-config*(8). == loop-AES EXTENSION -Cryptsetup supports mapping loop-AES encrypted partition using a compatibility mode. +Cryptsetup supports mapping a loop-AES encrypted partition using a compatibility mode. === OPEN *open --type loopaes --key-file * + @@ -231,19 +231,19 @@ See also section 7 of the FAQ and http://loop-aes.sourceforge.net[loop-AES] for == TCRYPT (TrueCrypt and VeraCrypt compatible) EXTENSION -Cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt encrypted partition using a native Linux kernel API. -Header formatting and TCRYPT header change is not supported, cryptsetup never changes TCRYPT header on-device. +Cryptsetup supports mapping of TrueCrypt, tcplay, or VeraCrypt encrypted partitions using a native Linux kernel API. +Header formatting and TCRYPT header change are not supported; cryptsetup never changes the TCRYPT header on-device. -TCRYPT extension requires kernel userspace crypto API to be available (introduced in Linux kernel 2.6.38). -If you are configuring kernel yourself, enable "User-space interface for symmetric key cipher algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option). +TCRYPT extension requires the kernel userspace crypto API to be available (introduced in Linux kernel 2.6.38). +If you are configuring the kernel yourself, enable "User-space interface for symmetric key cipher algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option). -Because TCRYPT header is encrypted, you have to always provide valid passphrase and keyfiles. +Because the TCRYPT header is encrypted, you must always provide a valid passphrase and keyfiles. -Cryptsetup should recognize all header variants, except legacy cipher chains using LRW encryption mode with 64 bits encryption block (namely Blowfish in LRW mode is not recognized, this is limitation of kernel crypto API). +Cryptsetup should recognize all header variants, except legacy cipher chains using LRW encryption mode with a 64-bit encryption block (namely, Blowfish in LRW mode is not recognized; this is a limitation of the kernel crypto API). -VeraCrypt is extension of TrueCrypt header with increased iteration count so unlocking can take quite a lot of time. +VeraCrypt is an extension of TrueCrypt with an increased iteration count, so unlocking can take quite a lot of time. -To open a VeraCrypt device with a custom Personal Iteration Multiplier (PIM) value, use either the --veracrypt-pim PIM option to directly specify the PIM on the command- line or use --veracrypt-query-pim*to be prompted for the PIM. +To open a VeraCrypt device with a custom Personal Iteration Multiplier (PIM) value, use either the --veracrypt-pim PIM option to directly specify the PIM on the command line or use --veracrypt-query-pim to be prompted for the PIM. The PIM value affects the number of iterations applied during key derivation. Please refer to https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html[PIM] for more detailed information. @@ -254,15 +254,15 @@ If you need to disable VeraCrypt device support, use --disable-veracrypt option. The *tcryptDump* command should work for all recognized TCRYPT devices and doesn't require superuser privilege. -To map system device (device with boot loader where the whole encrypted system resides) use --tcrypt-system option. +To map the system device (device with boot loader where the whole encrypted system resides), use --tcrypt-system option. Please read specific info in *cryptsetup-tcryptOpen*(8) --tcrypt-system option section as mapping system-encrypted device is tricky. -To use hidden header (and map hidden device, if available), use --tcrypt-hidden option. +To use a hidden header (and map hidden device, if available), use --tcrypt-hidden option. -To explicitly use backup (secondary) header, use --tcrypt-backup option. +To explicitly use the backup (secondary) header, use --tcrypt-backup option. *NOTE:* There is no protection for a hidden volume if the outer volume is mounted. -The reason is that if there were any protection, it would require some metadata describing what to protect in the outer volume and the hidden volume would become detectable. +The reason is that if there were any protection, it would require some metadata describing what to protect in the outer volume, and the hidden volume would become detectable. === OPEN *open --type tcrypt * + @@ -279,25 +279,25 @@ See *cryptsetup-tcryptDump*(8). See also https://en.wikipedia.org/wiki/TrueCrypt[TrueCrypt] and https://en.wikipedia.org/wiki/VeraCrypt[VeraCrypt] pages for more information. -Please note that cryptsetup does not use TrueCrypt or VeraCrypt code, please report all problems related to this compatibility extension to the cryptsetup project. +Please note that cryptsetup does not use TrueCrypt or VeraCrypt code; please report all problems related to this compatibility extension to the cryptsetup project. == BITLK (Windows BitLocker compatible) EXTENSION -Cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted partition using a native Linux kernel API. -Header formatting and BITLK header changes are not supported, cryptsetup never changes BITLK header on-device. +Cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted partitions using a native Linux kernel API. +Header formatting and BITLK header changes are not supported; cryptsetup never changes the BITLK header on-device. -BITLK extension requires kernel userspace crypto API to be available (for details see TCRYPT section). +BITLK extension requires the kernel userspace crypto API to be available (for details, see the TCRYPT section). -Cryptsetup should recognize all BITLK header variants, except legacy header used in Windows Vista systems and partially decrypted BitLocker devices. -Activation of legacy devices encrypted in CBC mode requires at least Linux kernel version 5.3 and for devices using Elephant diffuser kernel 5.6. +Cryptsetup should recognize all BITLK header variants, except the legacy header used in Windows Vista systems and partially decrypted BitLocker devices. +Activation of legacy devices encrypted in CBC mode requires at least a Linux kernel version 5.3, and for devices using the Elephant diffuser, kernel 5.6. The *bitlkDump* command should work for all recognized BITLK devices and doesn't require superuser privilege. -For unlocking with the *open* a password or a recovery passphrase or a startup key must be provided. +For unlocking with the *open*, a password, a recovery passphrase, or a startup key must be provided. -Additionally unlocking using volume key is supported. +Additionally, unlocking using the volume key is supported. You must provide BitLocker Full Volume Encryption Key (FVEK) using the --volume-key-file option. -The key must be decrypted and without the header (only 128/256/512 bits of key data depending on used cipher and mode). +The key must be decrypted and without the header (only 128/256/512 bits of key data depending on the used cipher and mode). Other unlocking methods (TPM, SmartCard) are not supported. @@ -314,7 +314,7 @@ See *cryptsetup-open*(8). Dump the header information of a BITLK device. + See *cryptsetup-bitlkDump*(8). -Please note that cryptsetup does not use any Windows BitLocker code, please report all problems related to this compatibility extension to the cryptsetup project. +Please note that cryptsetup does not use any Windows BitLocker code; please report all problems related to this compatibility extension to the cryptsetup project. == FVAULT2 (Apple macOS FileVault2 compatible) EXTENSION @@ -325,7 +325,7 @@ It does NOT support the new version of FileVault based on the APFS filesystem us Header formatting and FVAULT2 header changes are not supported; cryptsetup never changes the FVAULT2 header on-device. -FVAULT2 extension requires kernel userspace crypto API to be available (for details, see TCRYPT section) and kernel driver for HFS+ (hfsplus) filesystem. +FVAULT2 extension requires the kernel userspace crypto API to be available (for details, see the TCRYPT section) and a kernel driver for the HFS+ (hfsplus) filesystem. Cryptsetup should recognize the basic configuration for portable drives. @@ -344,22 +344,22 @@ See *cryptsetup-open*(8). == SED (Self Encrypting Drive) OPAL EXTENSION Cryptsetup supports using native hardware encryption on drives that provide an *OPAL* interface, both nested with *dm-crypt* and standalone. -Passphrases, tokens and metadata are stored using the LUKS2 header format, and are thus compatible with any software or system that uses LUKS2 (e.g.: tokens). +Passphrases, tokens and metadata are stored using the LUKS2 header format, and are thus compatible with any software or system that uses LUKS2 (e.g., tokens). -*WARNING:* this support is new and experimental, and requires at least kernel v6.4. +*WARNING:* This support is new and experimental, and requires at least kernel v6.4. Resizing devices is not supported. The --hw-opal can be specified for OPAL + dm-crypt, and --hw-opal-only can be specified to use OPAL only, without a dm-crypt layer. -Opening, closing and enrolling tokens work in the same way as with LUKS2 and dm-crypt. -The new parameters are only necessary when formatting, the LUKS2 metadata will ensure the right setup is performed when opening or closing. +Opening, closing and enrolling tokens work the same way as with LUKS2 and dm-crypt. +The new parameters are only necessary when formatting; the LUKS2 metadata will ensure the right setup is performed when opening or closing. If no *subsystem* is specified, it will be automatically set to *HW-OPAL* so that it is immediately apparent when a device uses OPAL. === FORMAT *luksFormat --type luks2 --hw-opal []* Additionally specify --hw-opal-only instead of --hw-opal to avoid the dm-crypt layer. -Other than the usual passphrase, an admin password will have to be specified when formatting the first partition of the drive, and will have to be re-supplied when formatting any other partition until a factory reset is performed. +Other than the usual passphrase, an admin password will have to be specified when formatting the drive's first partition, and will have to be re-supplied when formatting any other partition until a factory reset is performed. === ERASE *erase * @@ -368,9 +368,9 @@ Securely erase a partition or device. Requires admin password. Additionally specify --hw-opal-factory-reset for a FULL factory reset of the drive, using the drive's *PSID* (typically printed on the label) instead of the admin password. -*NOTE*: PSID must be entered without any dashes, spaces or underscores. +*NOTE*: PSID must be entered without dashes, spaces or underscores. -*WARNING*: a factory reset will cause ALL data on the device to be lost, regardless of the partition it is ran on, if any, and regardless of any LUKS2 header backup. +*WARNING*: A factory reset will cause ALL data on the device to be lost, regardless of the partition it is run on, if any, and regardless of any LUKS2 header backup. == MISCELLANEOUS ACTIONS @@ -384,13 +384,13 @@ See *cryptsetup-repair*(8). === BENCHMARK *benchmark * -Benchmarks ciphers and KDF (key derivation function). + +Benchmarks, ciphers and KDF (key derivation function). + See *cryptsetup-benchmark*(8). == PLAIN DM-CRYPT OR LUKS? Unless you understand the cryptographic background well, use LUKS. -With plain dm-crypt there are a number of possible user errors that massively decrease security. +With plain dm-crypt, there are a number of possible user errors that massively decrease security. While LUKS cannot fix them all, it can lessen the impact for many of them. == WARNINGS @@ -402,40 +402,40 @@ Nonetheless, some risks deserve to be mentioned here. *Backup:* Storage media die. Encryption has no influence on that. Backup is mandatory for encrypted data as well, if the data has any worth. -See the Cryptsetup FAQ for advice on how to do a backup of an encrypted volume. +See the Cryptsetup FAQ for advice on how to back up an encrypted volume. *Character encoding:* If you enter a passphrase with special symbols, the passphrase can change depending on character encoding. -Keyboard settings can also change, which can make blind input hard or impossible. -For example, switching from some ASCII 8-bit variant to UTF-8 can lead to a different binary encoding and hence different passphrase seen by cryptsetup, even if what you see on the terminal is exactly the same. +Keyboard settings can also be changed, which can make blind input hard or impossible. +For example, switching from some ASCII 8-bit variant to UTF-8 can lead to a different binary encoding and hence a different passphrase seen by cryptsetup, even if what you see on the terminal is exactly the same. It is therefore highly recommended to select passphrase characters only from 7-bit ASCII, as the encoding for 7-bit ASCII stays the same for all ASCII variants and UTF-8. -*LUKS header:* If the header of a LUKS volume gets damaged, all data is permanently lost unless you have a header-backup. -If a key-slot is damaged, it can only be restored from a header-backup or if another active key-slot with known passphrase is undamaged. +*LUKS header:* If the header of a LUKS volume gets damaged, all data is permanently lost unless you have a header backup. +If a keyslot is damaged, it can only be restored from a header backup or if another active keyslot with a known passphrase is undamaged. Damaging the LUKS header is something people manage to do with surprising frequency. -This risk is the result of a trade-off between security and safety, as LUKS is designed for fast and secure wiping by just overwriting header and key-slot area. +This risk is the result of a trade-off between security and safety, as LUKS is designed for fast and secure wiping by just overwriting the header and keyslot area. -*Previously used partitions:* If a partition was previously used, it is a very good idea to wipe filesystem signatures, data, etc. before creating a LUKS or plain dm-crypt container on it. +*Previously used partitions:* If a partition was previously used, it is a very good idea to wipe filesystem signatures, data, etc., before creating a LUKS or plain dm-crypt container. For a quick removal of filesystem signatures, use *wipefs*(8). -Take care though that this may not remove everything. +This may not remove everything. In particular, MD RAID signatures at the end of a device may survive. It also does not remove data. -For a full wipe, overwrite the whole partition before container creation. +For a full wipe, overwrite the whole partition before creating a container. If you do not know how to do that, the cryptsetup FAQ describes several options. == EXAMPLES Example 1: Create LUKS 2 container on block device /dev/sdX.:: sudo cryptsetup --type luks2 luksFormat /dev/sdX -Example 2: Add an additional passphrase to key slot 5.:: +Example 2: Add an additional passphrase to keyslot 5.:: sudo cryptsetup luksAddKey --key-slot 5 /dev/sdX -Example 3: Create LUKS header backup and save it to file.:: +Example 3: Create LUKS header backup and save it to a file.:: sudo cryptsetup luksHeaderBackup /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile Example 4: Open LUKS container on /dev/sdX and map it to sdX_crypt.:: sudo cryptsetup open /dev/sdX sdX_crypt -*WARNING: The command in example 5 will erase all key slots.*:: - Your cannot use your LUKS container afterward anymore unless you have a backup to restore. -Example 5: Erase all key slots on /dev/sdX.:: +*WARNING: The command in example 5 will erase all keyslots.*:: + You cannot use your LUKS container afterward anymore unless you have a backup to restore. +Example 5: Erase all keyslots on /dev/sdX.:: sudo cryptsetup erase /dev/sdX Example 6: Restore LUKS header from backup file.:: sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file @@ -455,20 +455,20 @@ Note that no iterated hashing or salting is done in plain mode. If hashing is done, it is a single direct hash. This means that low-entropy passphrases are easy to attack in plain mode. -*From a terminal*: The passphrase is read until the first newline, i.e. '\n'. +*From a terminal*: The passphrase is read until the first newline, i.e., '\n'. The input without the newline character is processed with the default hash or the hash specified with --hash. The hash result will be truncated to the key size of the used cipher, or the size specified with -s. *From stdin*: Reading will continue until a newline (or until the maximum input size is reached), with the trailing newline stripped. -The maximum input size is defined by the same compiled-in default as for the maximum key file size and can be overwritten using --keyfile-size option. +The maximum input size is defined by the same compiled-in default as the maximum key file size and can be overwritten using the --keyfile-size option. The data read will be hashed with the default hash or the hash specified with --hash. The hash result will be truncated to the key size of the used cipher, or the size specified with -s. Note that if --key-file=- is used for reading the key from stdin, trailing newlines are not stripped from the input. -If "plain" is used as argument to --hash, the input data will not be hashed. -Instead, it will be zero padded (if shorter than the key size) or truncated (if longer than the key size) and used directly as the binary key. +If "plain" is used as an argument to --hash, the input data will not be hashed. +Instead, it will be zero-padded (if shorter than the key size) or truncated (if longer than the key size) and used directly as the binary key. This is useful for directly specifying a binary key. No warning will be given if the amount of data read from stdin is less than the key size. @@ -478,7 +478,7 @@ No warning will be given if the amount of data read from stdin is less than the The --hash option is usable only for stdin input in plain mode. If the key file is shorter than the key, cryptsetup will quit with an error. -The maximum input size is defined by the same compiled-in default as for the maximum key file size and can be overwritten using --keyfile-size option. +The maximum input size is defined by the same compiled-in default as the maximum key file size and can be overwritten using the --keyfile-size option. === Passphrase processing for LUKS @@ -493,13 +493,13 @@ If --keyfile-size is given, it is ignored. Newline characters do not terminate the input. The --keyfile-size option can be used to limit what is read. -*Passphrase processing*: Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat), the user may specify how much the time the passphrase processing should consume. -The time is used to determine the iteration count for PBKDF2 and higher times will offer better protection for low-entropy passphrases, but open will take longer to complete. +*Passphrase processing*: Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat), the user may specify how much time the passphrase processing should consume. +The time is used to determine the iteration count for PBKDF2, and higher times will offer better protection for low-entropy passphrases, but the open command will take longer to complete. For passphrases that have entropy higher than the used key length, higher iteration times will not increase security. The default setting of one or two seconds is sufficient for most practical cases. The only exception is a low-entropy passphrase used on a device with a slow CPU, as this will result in a low iteration count. -On a slow device, it may be advisable to increase the iteration time using the --iter-time option in order to obtain a higher iteration count. +On a slow device, it may be advisable to increase the iteration time using the --iter-time option to obtain a higher iteration count. This does slow down all later luksOpen operations accordingly. === Incoherent behavior for invalid passphrases/keys @@ -513,7 +513,7 @@ If the given passphrase is wrong, the device mapped by plain dm-crypt will essen The available combinations of ciphers, modes, hashes and key sizes depend on kernel support. See /proc/crypto for a list of available options. -You might need to load additional kernel crypto modules in order to get more options. +You might need to load additional kernel crypto modules to get more options. For the --hash option, if the crypto backend is libgcrypt, then all algorithms supported by the gcrypt library are available. For other crypto backends, some algorithms may be missing. @@ -522,56 +522,56 @@ For other crypto backends, some algorithms may be missing. Mathematics can't be bribed. Make sure you keep your passphrases safe. -There are a few nice tricks for constructing a fallback, when suddenly out of the blue, your brain refuses to cooperate. +There are a few nice tricks for constructing a fallback when suddenly, out of the blue, your brain refuses to cooperate. These fallbacks need LUKS, as it's only possible with LUKS to have multiple passphrases. Still, if your attacker model does not prevent it, storing your passphrase in a sealed envelope somewhere may be a good idea as well. === Notes on Random Number Generators -Random Number Generators (RNG) used in cryptsetup are always the kernel RNGs without any modifications or additions to data stream produced. +Random Number Generators (RNGs) used in cryptsetup are always the kernel RNGs without any modifications or additions to the data stream produced. -There are two types of randomness cryptsetup/LUKS needs. +There are two types of randomness that cryptsetup/LUKS needs. One type (which always uses /dev/urandom) is used for salts, the AF splitter and for wiping deleted keyslots. The second type is used for the volume key. -You can switch between using /dev/random and /dev/urandom here, see *--use-random* and *--use-urandom* options. +You can switch between using /dev/random and /dev/urandom here, see --use-random and --use-urandom options. Using /dev/random on a system without enough entropy sources can cause *luksFormat* to block until the requested amount of random data is gathered. In a low-entropy situation (embedded system), this can take a very long time and potentially forever. At the same time, using /dev/urandom in a low-entropy situation will produce low-quality keys. This is a serious problem, but solving it is out of scope for a mere man-page. -See *urandom(4)* for more information. +See *urandom*(4) for more information. === Authenticated disk encryption (EXPERIMENTAL) Since Linux kernel version 4.12 dm-crypt supports authenticated disk encryption. -Normal disk encryption modes are length-preserving (plaintext sector is of the same size as a ciphertext sector) and can provide only confidentiality protection, but not cryptographically sound data integrity protection. +Normal disk encryption modes are length-preserving (the plaintext sector is the same size as a ciphertext sector) and can provide only confidentiality protection, not cryptographically sound data integrity protection. -Authenticated modes require additional space per-sector for authentication tag and use Authenticated Encryption with Additional Data (AEAD) algorithms. +Authenticated modes require additional space per-sector for the authentication tag and use Authenticated Encryption with Additional Data (AEAD) algorithms. -If you configure LUKS2 device with data integrity protection, there will be an underlying dm-integrity device, which provides additional per-sector metadata space and also provide data journal protection to ensure atomicity of data and metadata update. +If you configure a LUKS2 device with data integrity protection, there will be an underlying dm-integrity device, which provides additional per-sector metadata space and data journal protection to ensure atomicity of data and metadata updates. Because there must be additional space for metadata and journal, the available space for the device will be smaller than for length-preserving modes. The dm-crypt device then resides on top of such a dm-integrity device. -All activation and deactivation of this device stack is performed by cryptsetup, there is no difference in using *luksOpen* for integrity protected devices. -If you want to format LUKS2 device with data integrity protection, use *--integrity* option (see *cryptsetup-luksFormat(8)*). +All activation and deactivation of this device stack is performed by cryptsetup; there is no difference in using *luksOpen* for integrity-protected devices. +If you want to format a LUKS2 device with data integrity protection, use --integrity option (see *cryptsetup-luksFormat*(8)). -Albeit Linux kernel 5.7 added TRIM support for standalone dm-integrity devices, *cryptsetup(8)* can't offer support for discards (TRIM) in authenticated encryption mode, because the underlying dm-crypt kernel module does not support this functionality when dm-integrity is used as auth tag space allocator (see *--allow-discards* in *cryptsetup-open(8)*). +Albeit Linux kernel 5.7 added TRIM support for standalone dm-integrity devices, *cryptsetup*(8) can't offer support for discards (TRIM) in authenticated encryption mode, because the underlying dm-crypt kernel module does not support this functionality when dm-integrity is used as auth tag space allocator (see --allow-discards in *cryptsetup-open*(8)). -Some integrity modes requires two independent keys (key for encryption and for authentication). +Some integrity modes require two independent keys (a key for encryption and authentication). Both these keys are stored in one LUKS keyslot. -*WARNING:* All support for authenticated modes is experimental and there are only some modes available for now. -Note that there are a very few authenticated encryption algorithms that are suitable for disk encryption. -You also cannot use CRC32 or any other non-cryptographic checksums (other than the special integrity mode "none"). -If for some reason you want to have integrity control without using authentication mode, then you should separately configure dm-integrity independently of LUKS2. +*WARNING:* All support for authenticated modes is experimental, and only some modes are available now. +Note that very few authenticated encryption algorithms are suitable for disk encryption. +You also cannot use CRC32 or other non-cryptographic checksums (other than the special integrity mode "none"). +If, for some reason, you want to have integrity control without using authentication mode, then you should separately configure dm-integrity independently of LUKS2. === Notes on loopback device use Cryptsetup is usually used directly on a block device (disk partition or LVM volume). However, if the device argument is a file, cryptsetup tries to allocate a loopback device and map it into this file. -This mode requires Linux kernel 2.6.25 or more recent which supports the loop autoclear flag (loop device is cleared on the last close automatically). -Of course, you can always map a file to a loop-device manually. +This mode requires a Linux kernel 2.6.25 or more recent, which supports the loop autoclear flag (loop device is cleared on the last close automatically). +Of course, you can always map a file to a loop device manually. See the cryptsetup FAQ for an example. When device mapping is active, you can see the loop backing file in the status command output. @@ -579,19 +579,19 @@ Also see losetup(8). === LUKS2 header locking -The LUKS2 on-disk metadata is updated in several steps and to achieve proper atomic update, there is a locking mechanism. -For an image in file, code uses *flock(2)* system call. +The LUKS2 on-disk metadata is updated in several steps, and to achieve a proper atomic update, there is a locking mechanism. +For an image in a file, the code uses the *flock*(2) system call. For a block device, lock is performed over a special file stored in a locking directory (by default */run/cryptsetup*). The locking directory should be created with the proper security context by the distribution during the boot-up phase. -Only LUKS2 uses locks, other formats do not use this mechanism. +Only LUKS2 uses locks; other formats do not use this mechanism. === LUKS on-disk format specification -For LUKS on-disk metadata specification see https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification[LUKS1] and https://gitlab.com/cryptsetup/LUKS2-docs[LUKS2]. +For LUKS on-disk metadata specification, see https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification[LUKS1] and https://gitlab.com/cryptsetup/LUKS2-docs[LUKS2]. == AUTHORS -Cryptsetup is originally written by mailto:jana@saout.de[Jana Saout]. + +Cryptsetup was originally written by mailto:jana@saout.de[Jana Saout]. + The LUKS extensions and original man page were written by mailto:clemens@endorphin.org[Clemens Fruhwirth]. + Man page extensions by mailto:gmazyland@gmail.com[Milan Broz]. + Man page rewrite and extension by mailto:arno@wagner.name[Arno Wagner]. diff --git a/man/integritysetup.8.adoc b/man/integritysetup.8.adoc index 95902626..b9c226ce 100644 --- a/man/integritysetup.8.adoc +++ b/man/integritysetup.8.adoc @@ -6,7 +6,7 @@ == NAME -integritysetup - manage dm-integrity (block level integrity) volumes +integritysetup - manage dm-integrity (block-level integrity) volumes == SYNOPSIS @@ -16,9 +16,9 @@ integritysetup - manage dm-integrity (block level integrity) volumes Integritysetup is used to configure dm-integrity managed device-mapper mappings. -Device-mapper integrity target provides read-write transparent integrity checking of block devices. -The dm-integrity target emulates an additional data integrity field per-sector. -You can use this additional field directly with integritysetup utility, or indirectly (for authenticated encryption) through cryptsetup. +The device-mapper integrity target provides read-write transparent integrity checking for block devices. +The dm-integrity target emulates an additional data integrity field per sector. +You can use this additional field directly with the integritysetup utility, or indirectly (for authenticated encryption) through cryptsetup. == BASIC ACTIONS @@ -58,18 +58,18 @@ Reports status for the active integrity mapping . === DUMP *dump * -Reports parameters from on-disk stored superblock. +Report parameters from the on-disk stored superblock. === RESIZE *resize * Resizes an active mapping . -If --size (in 512-bytes sectors) or --device-size are not specified, the size is computed from the underlying device. +If --size (in 512-byte sectors) or --device-size is not specified, the size is computed from the underlying device. After resize, the *recalculating* flag is set. If --wipe flag is set and the size of the device is increased, the newly added section will be wiped. -Increasing the size of integrity volumes is available since the Linux kernel version 5.7, shrinking should work on older kernels too. +Increasing the size of integrity volumes has been possible since the Linux kernel version 5.7; shrinking should work on older kernels, too. ** can be [--size, --device-size, --wipe]. @@ -85,48 +85,49 @@ Do not ask for confirmation. Bitmap flush time in milliseconds. + *WARNING:* -In case of a crash, it is possible that the data and integrity tag doesn't match if the journal is disabled. +In case of a crash, it is possible that the data and integrity tag don't match if the journal is disabled. *--bitmap-sectors-per-bit* _sectors_:: -Number of 512-byte sectors per bitmap bit, the value must be power of two. +The number of 512-byte sectors per bitmap bit must be a power of two. *--buffer-sectors* _sectors_:: The number of sectors in one buffer. + -The tag area is accessed using buffers, the large buffer size means that the I/O size will be larger, but there could be less I/Os issued. +The tag area is accessed using buffers; the large buffer size means the I/O size will be larger, but there could be less I/Os issued. *--cancel-deferred*:: -Removes a previously configured deferred device removal in *close* command. +Removes a previously configured deferred device removal in the *close* command. *--data-device* __:: Specify a separate data device that contains existing data. -The then will contain calculated integrity tags and journal for data on . +The will then contain calculated integrity tags and a journal for data on . + -*NOTE:* To not wipe the data device after initial format, also specify --no-wipe option and activate with --integrity-recalculate to automatically recalculate integrity tags. +*NOTE:* To not wipe the data device after initial format, also specify --no-wipe option and activate with --integrity-recalculate to recalculate integrity tags automatically. *--debug*:: Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by *#*. *--deferred*:: -Defers device removal in *close* command until the last user closes it. +Defers device removal in the *close* command until the last user closes it. *--help*, *-?*:: Show help text and default parameters. *--integrity*, *-I* _algorithm_:: Use internal integrity calculation (standalone mode). -The integrity algorithm can be CRC (crc32c/crc32), non-cryptographic hash function (xxhash64) or hash function (sha1, sha256). +The integrity algorithm can be CRC (crc32c/crc32), a non-cryptographic hash function (xxhash64) or a hash function (sha1, sha256). + -For HMAC (hmac-sha256) you have also to specify an integrity key and its size. +For HMAC (hmac-sha256), you must specify an integrity key and its size. *--integrity-bitmap-mode*, *-B*:: -Use alternate bitmap mode (available since Linux kernel 5.2) where dm-integrity uses bitmap instead of a journal. +Use alternate bitmap mode (available since Linux kernel 5.2), where dm-integrity uses a bitmap instead of a journal. If a bit in the bitmap is 1, the corresponding region's data and integrity tags are not synchronized - if the machine crashes, the unsynchronized regions will be recalculated. -The bitmap mode is faster than the journal mode, because we don't have to write the data twice, but it is also less reliable, because if data corruption happens when the machine crashes, it may not be detected. +The bitmap mode is faster than the journal mode because we don't have to write the data twice. +However, it is also less reliable because if data corruption happens when the machine crashes, it may not be detected. *--integrity-inline*:: -Store integrity tags to hardware sector integrity fields. +Store integrity tags in hardware sector integrity fields. The device must support sectors with additional protection information (PI, also known as DIF - data integrity field) of the requested size. Another storage subsystem must not use the additional field (the device must present a "nop" profile in the kernel). Note that some devices must be reformatted at a low level to support this option; for NVMe devices, see nvme(1) id-ns LBA profiles. @@ -143,17 +144,17 @@ The size of the data integrity key. Maximum is 4096 bytes. *--integrity-no-journal*, *-D*:: -Disable journal for integrity device. +Disable the journal for the integrity device. *--integrity-recalculate*:: -Automatically recalculate integrity tags in kernel on activation. -The device can be used during automatic integrity recalculation but becomes fully integrity protected only after the background operation is finished. +Automatically recalculate integrity tags in the kernel on activation. +The device can be used during automatic integrity recalculation, but becomes fully integrity protected only after the background operation is finished. This option is available since the Linux kernel version 4.19. *--integrity-recalculate-reset*:: Restart recalculation from the beginning of the device. It can be used to change the integrity checksum function. -Note it does not change the tag length. +Note, it does not change the tag length. This option is available since the Linux kernel version 5.13. *--integrity-recovery-mode*, *-R*:: @@ -164,11 +165,11 @@ The number of interleaved sectors. *--journal-commit-time* _ms_:: Commit time in milliseconds. -When this time passes (and no explicit flush operation was issued), the journal is written. +The journal is written when this time passes (and no explicit flush operation was issued). *--journal-crypt* _algorithm_:: -Encryption algorithm for journal data area. -You can use a block cipher here such as cbc-aes or a stream cipher, for example, chacha20 or ctr-aes. +Encryption algorithm for the journal data area. +You can use a block cipher here, such as cbc-aes or a stream cipher, for example, chacha20 or ctr-aes. + *NOTE:* The journal encryption options are only intended for testing. Using journal encryption does not make sense without encryption of the data. @@ -181,7 +182,7 @@ The size of the journal encryption key. Maximum is 4096 bytes. *--journal-integrity* _algorithm_:: -Integrity algorithm for journal area. +Integrity algorithm for the journal area. See --integrity option for detailed specification. *--journal-integrity-key-file* _file_:: @@ -195,20 +196,20 @@ Maximum is 4096 bytes. Size of the journal. *--journal-watermark* _percent_:: -Journal watermark in percents. -When the size of the journal exceeds this watermark, the journal flush will be started. +Journal watermark in percent. +When the journal size exceeds this watermark, the journal flush will be started. *--no-wipe*:: -Do not wipe the device after format. +Do not wipe the device after formatting. A device that is not initially wiped will contain invalid checksums. *--progress-frequency* _seconds_:: -Print separate line every with wipe progress. +Print a separate line every with wipe progress. *--progress-json*:: -Prints wipe 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 wipe progress (except it's compact single line): +Prints wipe progress data in JSON format, which is suitable mostly for machine processing. +It prints a separate line every half second (or based on --progress-frequency value). +The JSON output looks as follows during wipe progress (except it's a compact single line): + .... { @@ -221,15 +222,15 @@ The JSON output looks as follows during wipe progress (except it's compact singl } .... + -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. +Note on numbers in JSON output: Due to JSON parsers' limitations, all numbers are represented in a string format due to the need for full 64-bit unsigned integers. *--sector-size*, *-s* _bytes_:: Sector size (power of two: 512, 1024, 2048, 4096). *--tag-size*, *-t* _bytes_:: -Size of the integrity tag per-sector (here the integrity function will store authentication tag). +Size of the integrity tag per-sector (here, the integrity function will store the authentication tag). + -*NOTE:* The size can be smaller that output size of the hash function, in that case only part of the hash will be stored. +*NOTE:* The size can be smaller than the output size of the hash function; in that case, only part of the hash will be stored. *--usage*:: Show short option help. @@ -241,13 +242,13 @@ Print more information on command execution. Show the program version. *--wipe*:: -Wipe the newly allocated area after resize to bigger size. -If this flag is not set, checksums will be calculated for the data previously stored in the newly allocated area. +Wipe the newly allocated area after resizing to a bigger size. +If this flag is not set, checksums will be calculated for previously stored data in the newly allocated area. == LEGACY COMPATIBILITY OPTIONS *WARNING:*:: -Do not use these options until you need compatibility with specific old kernel. +Do not use these options until you need compatibility with a specific old kernel. *--integrity-legacy-padding*:: Use inefficient legacy padding. @@ -267,7 +268,7 @@ Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory, *4* == NOTES The dm-integrity target is available since Linux kernel version 4.12. -Format and activation of an integrity device always require superuser privilege because the superblock is calculated and handled in dm-integrity kernel target. +Format and activation of an integrity device always require superuser privilege because the superblock is calculated and handled in the dm-integrity kernel target. == EXAMPLES @@ -293,7 +294,7 @@ Dump dm-integrity superblock information: == DM-INTEGRITY ON-DISK FORMAT -The on-disk format specification available at https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity[DMIntegrity] page. +The on-disk format specification is available on the https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity[DMIntegrity] page. == AUTHORS diff --git a/man/veritysetup.8.adoc b/man/veritysetup.8.adoc index daa609b7..79bcb38d 100644 --- a/man/veritysetup.8.adoc +++ b/man/veritysetup.8.adoc @@ -6,7 +6,7 @@ == NAME -veritysetup - manage dm-verity (block level verification) volumes +veritysetup - manage dm-verity (block-level verification) volumes == SYNOPSIS @@ -27,14 +27,14 @@ Veritysetup supports these operations: === FORMAT *format * -Calculates and permanently stores hash verification data for data_device. -Hash area can be located on the same device after data if specified by --hash-offset option. +Calculates and permanently stores hash verification data for the data_device. +Hash area can be located on the same device after data, if specified by --hash-offset option. -Note you need to provide root hash string for device verification or activation. +You need to provide the root hash string for device verification or activation. Root hash must be trusted. -The data or hash device argument can be block device or file image. -If hash device path doesn't exist, it will be created as file. +The data or hash device argument can be a block device or a file image. +If the hash device path doesn't exist, it will be created as a file. ** can be [--hash, --no-superblock, --format, --data-block-size, --hash-block-size, --data-blocks, --hash-offset, --salt, --uuid, --root-hash-file]. @@ -51,27 +51,27 @@ The is a hexadecimal string. ** can be [--hash-offset, --no-superblock, --ignore-corruption or --restart-on-corruption, --panic-on-corruption, --ignore-zero-blocks, --check-at-most-once, --root-hash-signature, --root-hash-file, --use-tasklets, --shared]. -If option --root-hash-file is used, the root hash is read from instead of from the command line parameter. -Expects hex-encoded text, without terminating newline. +If option --root-hash-file is used, the root hash is read from instead of the command line parameter. +Expects hex-encoded text, without a terminating newline. -If option --no-superblock is used, you have to use as the same options as in initial format operation. +If --no-superblock is used, you must use the same options as in the initial format operation. === VERIFY *verify * + *verify --root-hash-file * -Verifies data on data_device with use of hash blocks stored on hash_device. +Verifies data on data_device using hash blocks stored on hash_device. -This command performs userspace verification, no kernel device is created. +This command performs userspace verification; no kernel device is created. The is a hexadecimal string. -If option --root-hash-file is used, the root hash is read from instead of from the command line parameter. -Expects hex-encoded text, without terminating newline. +If option --root-hash-file is used, the root hash is read from instead of the command line parameter. +Expects hex-encoded text, without a terminating newline. ** can be [--hash-offset, --no-superblock, --root-hash-file]. -If option --no-superblock is used, you have to use as the same options as in initial format operation. +If --no-superblock is used, you must use the same options as in the initial format operation. === CLOSE *close * + @@ -89,7 +89,7 @@ Reports status for the active verity mapping . === DUMP *dump * -Reports parameters of verity device from on-disk stored superblock. +Report parameters of the verity device from the on-disk stored superblock. ** can be [--hash-offset]. @@ -98,28 +98,28 @@ Reports parameters of verity device from on-disk stored superblock. Do not ask for confirmation. *--cancel-deferred*:: -Removes a previously configured deferred device removal in *close* command. +Cancels a previously configured deferred device removal in the *close* command. *--check-at-most-once*:: -Instruct kernel to verify blocks only the first time they are read from the data device, rather than every time. +Instruct the kernel to verify blocks only once they are read from the data device, rather than every time. + *WARNING:* It provides a reduced level of security because only offline tampering of the data device's content will be detected, not online tampering. This option is available since Linux kernel version 4.17. *--data-blocks* _blocks_:: -Size of data device used in verification. +Size of the data device used in verification. If not specified, the whole device is used. *--data-block-size* _bytes_:: Used block size for the data device. -(Note kernel supports only page-size as maximum here.) +Maximum is the page size used by the kernel. *--debug*:: Run in debug mode with full diagnostic logs. Debug output lines are always prefixed by *#*. *--deferred*:: -Defers device removal in *close* command until the last user closes it. +Defers device removal in the *close* command until the last user closes it. *--error-as-corruption*:: Handle device I/O errors the same as data corruption. @@ -129,94 +129,94 @@ This option must be combined with --restart-on-corruption or --panic-on-corrupti Use forward error correction (FEC) to recover from corruption if hash verification fails. Use encoding data from the specified device. + -The fec device argument can be block device or file image. -For format, if fec device path doesn't exist, it will be created as file. +The FEC device argument can be a block device or a file image. +For format, if the FEC device path doesn't exist, it will be created as a file. + Block sizes for data and hash devices must match. -Also, if the verity data_device is encrypted the fec_device should be too. +Also, if the verity data_device is encrypted, the fec_device should be too. + -FEC calculation covers data, hash area, and optional foreign metadata stored on the same device with the hash tree (additional space after hash area). -Size of this optional additional area protected by FEC is calculated from image sizes, so you must be sure that you use the same images for activation. +FEC calculation covers data, hash area, and optional foreign metadata stored on the same device as the hash tree (additional space after the hash area). +The size of this optional additional area protected by FEC is calculated from image sizes, so you must use the same images for activation. + -If the hash device is in a separate image, metadata covers the whole rest of the image after the hash area. +If the hash device is in a separate image, metadata covers the entire image after the hash area. + -If hash and FEC device is in the image, metadata ends on the FEC area offset. +The metadata ends on the FEC area offset if the hash and FEC device are in the image. *--fec-offset* _bytes_:: This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding data. *--fec-roots* _number_:: Number of generator roots. -This equals to the number of parity bytes in the encoding data. +This equals the number of parity bytes in the encoding data. In RS(M, N) encoding, the number of roots is M-N. -M is 255 and M-N is between 2 and 24 (including). +M is 255, and M-N is between 2 and 24 (including). *--format* _number_:: Specifies the hash version type. -Format type 0 is original Chrome OS version. -Format type 1 is current version. +Format type 0 is the original Chrome OS version. +Format type 1 is the current version. *--hash* _hash_:: Hash algorithm for dm-verity. -For default see --help option. +For default, see --help option. *--hash-block-size* _bytes_:: Used block size for the hash device. -(Note kernel supports only page-size as maximum here.) +Maximum is the page size used by the kernel. *--hash-offset* _bytes_:: Offset of hash area/superblock on hash_device. -Value must be aligned to disk sector offset. +Value must be aligned with the disk sector offset. *--help*, *-?*:: Show help text and default parameters. *--ignore-corruption*, *--restart-on-corruption*, *--panic-on-corruption*:: -Defines what to do if data integrity problem is detected (data corruption). +Defines what to do if a data integrity problem (data corruption) is detected. + -Without these options kernel fails the IO operation with I/O error. -With --ignore-corruption option the corruption is only logged. -With --restart-on-corruption or --panic-on-corruption the kernel is restarted (panicked) immediately. -(You have to provide way how to avoid restart loops.) +Without these options, the kernel fails the I/O operation with an I/O error. +With --ignore-corruption option, the corruption is only logged. +With --restart-on-corruption or --panic-on-corruption, the kernel is restarted (panicked) immediately. +(You have to provide a way to avoid restart loops.) + *WARNING:* Use these options only for very specific cases. These options are available since Linux kernel version 4.1. *--ignore-zero-blocks*:: -Instruct kernel to not verify blocks that are expected to contain zeroes and always directly return zeroes instead. +Instruct the kernel not to verify blocks expected to contain zeroes and always directly return zeroes instead. + *WARNING:* Use this option only in very specific cases. This option is available since Linux kernel version 4.5. *--no-superblock*:: -Create or use dm-verity without permanent on-disk superblock. +Create or use dm-verity without a permanent on-disk superblock. *--root-hash-file* _file_*:: Path to file with stored root hash in hex-encoded text. *--root-hash-signature* _file_*:: -Path to root hash signature file used to verify the root hash (in kernel). -This feature requires Linux kernel version 5.4 or more recent. +A path to the root hash signature file used to verify the root hash (in kernel). +This feature requires a Linux kernel version 5.4 or more recent. *--salt=hex string*:: -Salt used for format or verification. +Salt used for formatting or verification. Format is a hexadecimal string. *--shared*:: -Allows data device to be used in shared mode. -The data device is not checked for exclusive access in-before the device activation and may be mapped in multiple verity mappings. +Allows the data device to be used in shared mode. +The data device is not checked for exclusive access before the device activation and may be mapped in multiple verity mappings. *--usage*:: Show short option help. *--use-tasklets*:: -Try to use kernel tasklets in dm-verity driver for performance reasons. +Try to use kernel tasklets in the dm-verity driver for performance reasons. This option is available since Linux kernel version 6.0. *--uuid* _UUID_:: -Use the provided UUID for format command instead of generating new one. +Use the provided UUID for the format command instead of generating a new one. + -The UUID must be provided in standard UUID format, e.g. 12345678-1234-1234-1234-123456789abc. +The UUID must be provided in standard UUID format, e.g., 12345678-1234-1234-1234-123456789abc. *--verbose*, *-v*:: Print more information on command execution. @@ -234,23 +234,23 @@ Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory, *4* *veritysetup --data-blocks=256 format * -Calculates and stores verification data on hash_device for the first 256 blocks (of block-size). -If hash_device does not exist, it is created (as file image). +Calculates and stores verification data on hash_device for the first 256 blocks (of block size). +If hash_device does not exist, it is created (as a file image). *veritysetup format --root-hash-file * -Calculates and stores verification data on hash_device for the whole data_device, and store the root hash as hex-encoded text in . +Calculates and stores verification data on hash_device for the whole data_device, and stores the root hash as hex-encoded text in . *veritysetup --data-blocks=256 --hash-offset=1052672 format * Verification data (hashes) is stored on the same device as data (starting at hash-offset). -Hash-offset must be greater than number of blocks in data-area. +Hash offset must be greater than the number of blocks in the data area. *veritysetup --data-blocks=256 --hash-offset=1052672 create test-device * Activates the verity device named test-device. Options --data-blocks and --hash-offset are the same as in the format command. -The was calculated in format command. +The was calculated in the format command. *veritysetup --data-blocks=256 --hash-offset=1052672 verify * @@ -259,15 +259,15 @@ Verifies device without activation (in userspace). *veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file verify * Verifies device without activation (in userspace). -Root hash passed via a file rather than inline. +Root hash is passed via file rather than inline. *veritysetup --fec-device= --fec-roots=10 format * -Calculates and stores verification and encoding data for data_device. +Calculates and stores verification and encoding data for the data_device. == DM-VERITY ON-DISK SPECIFICATION -The on-disk format specification is available at https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[DMVerity] page. +The on-disk format specification is available on the https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[DMVerity] page. == AUTHORS