diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/common_options.adoc | 1572 | ||||
| -rw-r--r-- | man/cryptsetup-ssh.8.adoc | 18 | ||||
| -rw-r--r-- | man/integritysetup.8.adoc | 240 | ||||
| -rw-r--r-- | man/veritysetup.8.adoc | 147 |
4 files changed, 988 insertions, 989 deletions
diff --git a/man/common_options.adoc b/man/common_options.adoc index 497d7fd..5c11309 100644 --- a/man/common_options.adoc +++ b/man/common_options.adoc @@ -1,5 +1,46 @@ == OPTIONS +ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--align-payload <number of 512 byte sectors>*:: +Align payload at a boundary of _value_ 512-byte sectors. ++ +If not specified, cryptsetup tries to use the topology info provided by +the kernel for the underlying device to get the optimal alignment. If +not available (or the calculated value is a multiple of the default) +data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte +sectors). ++ +For a detached LUKS header, this option specifies the offset on the data +device. See also the --header option. ++ +*WARNING:* This option is DEPRECATED and has often unexpected impact to +the data offset and keyslot area size (for LUKS2) due to the complex +rounding. For fixed data device offset use _--offset_ option instead. +endif::[] + +ifdef::ACTION_OPEN,ACTION_REFRESH[] +*--allow-discards*:: +Allow the use of discard (TRIM) requests for the device. This is also not +supported for LUKS2 devices with data integrity protection. ++ +*WARNING:* This command can have a negative security impact because it +can make filesystem-level operations visible on the physical device. For +example, information leaking filesystem type, used space, etc. may be +extractable from the physical device if the discarded blocks can be +located later. If in doubt, do not use it. ++ +A kernel version of 3.1 or later is needed. For earlier kernels, this +option is ignored. +endif::[] + +ifdef::COMMON_OPTIONS[] +*--batch-mode, -q*:: +Suppresses all confirmation questions. Use with care! ++ +If the --verify-passphrase option is not specified, this option also +switches off the passphrase verification. +endif::[] + ifdef::ACTION_REENCRYPT[] *--block-size* _value_ *(LUKS1 only)*:: Use re-encryption block size of _value_ in MiB. @@ -7,40 +48,178 @@ Use re-encryption block size of _value_ in MiB. Values can be between 1 and 64 MiB. endif::[] +ifdef::ACTION_CLOSE[] +*--cancel-deferred*:: +Removes a previously configured deferred device removal in _close_ +command. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_TCRYPTDUMP,ACTION_BENCHMARK[] +*--cipher, -c* _<cipher-spec>_:: +ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] +Set the cipher specification string for _plain_ device type. ++ +For _tcrypt_ device type it restricts checked cipher chains when looking for header. +endif::[] +ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_TCRYPTDUMP[] +Set the cipher specification string. +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. +*LUKS2*: +Set the cipher specification string for data segment only. + -Useful if direct-io operations perform better than normal buffered -operations (e.g. in virtual environments). +*LUKS1*: +Set the cipher specification string for data segment and keyslots. ++ +*NOTE*: In encrypt mode, if cipher specification is omitted the default cipher is applied. +In reencrypt mode, if no new cipher specification is requested, the existing cipher will remain +in use. Unless the existing cipher was "cipher_null". In that case default cipher would +be applied as in encrypt mode. +endif::[] +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] ++ +_cryptsetup --help_ shows the compiled-in defaults. ++ +If a hash is part of the cipher specification, then it is used as part +of the IV generation. For example, ESSIV needs a hash function, while +"plain64" does not and hence none is specified. ++ +For XTS mode you can optionally set a key size of 512 bits with the -s +option. Key size for XTS mode is twice that for other modes for the same +security level. +endif::[] +endif::[] + +ifdef::COMMON_OPTIONS[] +*--debug or --debug-json*:: +Run in debug mode with full diagnostic logs. Debug output lines are +always prefixed by *#*. ++ +If --debug-json is used, additional LUKS2 JSON data structures are printed. endif::[] ifdef::ACTION_REENCRYPT[] -*--use-fsync (LUKS1 only)*:: -Use fsync call after every written block. This applies for reencryption -log files as well. +*--decrypt*:: +Initialize (and run) device decryption mode. +endif::[] + +ifdef::ACTION_CLOSE[] +*--deferred*:: +Defers device removal in _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. +endif::[] +ifdef::ACTION_RESIZE[] +Sets new size of the device. If unset real device size is used. +endif::[] +ifdef::ACTION_OPEN[] +Usable only with _plain_ device 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. +It means that only specified area (from the start of the device +to the specified size) will be reencrypted. ++ +*WARNING:* This is destructive operation. Data beyond --device-size limit may +be lost after operation gets 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). endif::[] -ifdef::ACTION_ISLUKS[] -*--verbose, -v*:: -Print more information on command execution. +ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--disable-blkid*:: +Disable use of blkid library for checking and wiping on-disk signatures. 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 <device-type>*:: -ifndef::ACTION_REENCRYPT[] -Specifies required device type, for more info read _BASIC ACTIONS_ section in *cryptsetup*(8). +ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_RESIZE,ACTION_TOKEN[] +*--disable-external-tokens*:: +Disable loading of plugins for external LUKS2 tokens. +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. 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. ++ ifdef::ACTION_REENCRYPT[] -Specifies required (encryption mode) or expected (other modes) LUKS format. Accepts only _luks1_ or _luks2_. +*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. ++ +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). +endif::[] + +ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] +*--disable-veracrypt*:: +This option can be used to disable VeraCrypt compatible mode (only +TrueCrypt devices are recognized). Only for TCRYPT extension. See +_TCRYPT_ section in *cryptsetup*(8) for more info. +endif::[] + +ifdef::ACTION_LUKSDUMP[] +*--dump-json-metadata*:: +For _luksDump_ (LUKS2 only) this option prints content of LUKS2 header +JSON metadata area. +endif::[] + +ifdef::ACTION_LUKSDUMP,ACTION_TCRYPTDUMP,ACTION_BITLKDUMP[] +*--dump-volume-key, --dump-master-key (OBSOLETE alias)*:: +Print the volume key in the displayed information. Use with care, +as the volume key can be used to bypass +the passphrases, see also option --volume-key-file. +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--encrypt, --new, -N*:: +Initialize (and run) device in-place encryption mode. +endif::[] + +ifdef::ACTION_RESIZE,ACTION_OPEN,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_LUKSRESUME,ACTION_TOKEN[] +*--external-tokens-path* _absolute_path_:: +Override system directory path where cryptsetup searches for external token +handlers (or token plugins). It must be absolute path (starting with '/' character). +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--force-offline-reencrypt (LUKS2 only)*:: +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. ++ +*WARNING:* Use with extreme caution! This may destroy data if the device +is activated and/or actively used. endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] +*--force-password*:: +Do not use password quality checking for new LUKS passwords. ++ +This option is ignored if cryptsetup is built without password +quality checking support. ++ +For more info about password quality check, see the manual page for +*pwquality.conf(5)* and *passwdqc.conf(5)*. endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_TCRYPTDUMP,ACTION_BENCHMARK,ACTION_REENCRYPT[] @@ -74,50 +253,182 @@ Use _cryptsetup --help_ to show the defaults. endif::[] endif::[] -ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_TCRYPTDUMP,ACTION_BENCHMARK[] -*--cipher, -c* _<cipher-spec>_:: -ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] -Set the cipher specification string for _plain_ device type. +ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP[] +*--header <device or file storing the LUKS 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. + -For _tcrypt_ device type it restricts checked cipher chains when looking for header. endif::[] -ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_TCRYPTDUMP[] -Set the cipher specification string. +ifdef::ACTION_OPEN[] +Specify detached (separated) metadata device or file where the header is stored. ++ +*WARNING:* There is no check whether the ciphertext device specified +actually belongs to the header given. In fact, you can specify an +arbitrary device as the ciphertext device with the --header option. +Use with care. +endif::[] +ifndef::ACTION_REENCRYPT[] +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. +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. +endif::[] endif::[] ifdef::ACTION_REENCRYPT[] +If used with --encrypt/--new option, the header file will be created (or overwritten). +Use with care. ++ *LUKS2*: -Set the cipher specification string for data segment only. +For decryption mode the option may be used to export 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. + -*LUKS1*: -Set the cipher specification string for data segment and keyslots. +*WARNING:* Never put exported header file in a filesystem on top of 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. +endif::[] +endif::[] + +ifdef::ACTION_LUKSHEADERBACKUP,ACTION_LUKSHEADERRESTORE[] +*--header-backup-file <file>*:: +Specify file with header backup file. +endif::[] + +ifdef::COMMON_OPTIONS[] +*--help, -?*:: +Show help text and default parameters. +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 <size> due to other limitations (free space in keyslots +area or available memory). + -*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. +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. endif::[] -ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] + +ifdef::ACTION_LUKSFORMAT[] +*--hw-opal*:: +Format LUKS2 device with dm-crypt encryption stacked on top HW based encryption configured +on SED OPAL locking range. This option enables both SW and HW based data encryption. +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. +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--init-only (LUKS2 only)*:: +Initialize reencryption (any mode) operation in LUKS2 metadata only +and exit. If any reencrypt operation is already initialized in +metadata, the command with --init-only parameter fails. +endif::[] + +ifdef::ACTION_LUKSFORMAT[] +*--integrity <integrity algorithm>*:: +Specify integrity algorithm to be used for authenticated disk +encryption in LUKS2. + -_cryptsetup --help_ shows the compiled-in defaults. +*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). + -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 more info, see _AUTHENTICATED DISK ENCRYPTION_ section in *cryptsetup*(8). +endif::[] + +ifdef::ACTION_LUKSFORMAT[] +*--integrity-legacy-padding*:: +Use inefficient legacy padding. + -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. +*WARNING*: Do not use this option until you need compatibility with 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. +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. ++ +*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. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] +*--iter-time, -i <number of milliseconds>*:: +ifndef::ACTION_REENCRYPT[] +The number of milliseconds to spend with PBKDF passphrase processing. +Specifying 0 as 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. endif::[] endif::[] -ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_REPAIR,ACTION_TCRYPTDUMP,ACTION_REENCRYPT[] -*--verify-passphrase, -y*:: -When interactively asking for a passphrase, ask for it twice and -complain if both inputs do not match. ifdef::ACTION_OPEN[] -Advised when creating a _plain_ type mapping for the first time. +*--iv-large-sectors*:: +Count Initialization Vector (IV) in larger sector size (if set) +instead of 512 bytes sectors. This option can be used only with _plain_ +device type. ++ +*NOTE:* This option does not have any performance or security impact, +use it only for accessing incompatible existing disk images from other +systems that require this option. endif::[] -Ignored on input from file or stdin. + +ifdef::ACTION_TOKEN[] +*--json-file*:: +Read token JSON from a file or write token to it. --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. ++ +*LUKS1*: +Reencrypt only the LUKS1 header and keyslots. Skips data in-place reencryption. +endif::[] + +ifdef::ACTION_TOKEN[] +*--key-description <text>*:: +Set key description in keyring for use with _token_ command. 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[] @@ -186,133 +497,40 @@ This option is useful to cut trailing newlines, for example. If --keyfile-offset is also given, the size count starts after the offset. endif::[] -ifdef::ACTION_LUKSADDKEY[] -*--new-keyfile* _name_:: -Read the passphrase for a new keyslot from file. -+ -If the name given is "-", then the passphrase will be read from stdin. -In this case, reading will not stop at newline characters. +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_BENCHMARK,ACTION_LUKSADDKEY[] +*--key-size, -s* _bits_:: +ifndef::ACTION_LUKSADDKEY[] +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. + -This is alternative method to positional argument when adding new -passphrase via kefile. -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. -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. The default is to read the whole file up to -the compiled-in maximum length that can be queried with --help. -Supplying more than the compiled in maximum aborts the operation. When ---new-keyfile-offset is also given, reading starts after the offset. -endif::[] - -ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_BITLKDUMP,ACTION_REENCRYPT[] -*--volume-key-file, --master-key-file (OBSOLETE alias)*:: -ifndef::ACTION_REENCRYPT[] -Use a volume key stored in a file. -endif::[] -ifdef::ACTION_FORMAT[] +See /proc/crypto for more information. Note that key-size in +/proc/crypto is stated in bytes. + -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. + -endif::[] -ifdef::ACTION_LUKSDUMP,ACTION_BITLKDUMP[] -The volume key is stored in a file instead of being printed out to standard output. + 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. +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. endif::[] ifdef::ACTION_OPEN[] -This allows one to open _luks_ and _bitlk_ device types without giving a passphrase. + -endif::[] -ifdef::ACTION_REENCRYPT[] -Use (set) new volume key stored in a file. + -endif::[] -ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_REENCRYPT[] -*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. -endif::[] -endif::[] - -ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[] -*--volume-key-keyring* _<key description>_:: -Use a volume key stored in a keyring. -This allows one to open _luks_ and device types without giving a passphrase. -The key and associated type has to be readable from userspace so that volume -key digest may be verified in before activation. -+ -The _<key description>_ uses keyctl-compatible syntax. This can either be a -numeric key ID or a string name in the format _%<key type>:<key name>_. See -also *KEY IDENTIFIERS* section of *keyctl*(1). When no _%<key type>:_ prefix -is specified we assume the key type is _user_ (default type). -endif::[] - -ifdef::ACTION_LUKSDUMP[] -*--dump-json-metadata*:: -For _luksDump_ (LUKS2 only) this option prints content of LUKS2 header -JSON metadata area. -endif::[] - -ifdef::ACTION_LUKSDUMP,ACTION_TCRYPTDUMP,ACTION_BITLKDUMP[] -*--dump-volume-key, --dump-master-key (OBSOLETE alias)*:: -Print the volume key in the displayed information. Use with care, -as the volume key can be used to bypass -the passphrases, see also option --volume-key-file. -endif::[] - -ifdef::ACTION_TOKEN[] -*--json-file*:: -Read token JSON from a file or write token to it. --json-file=- reads JSON from -standard input or writes it to standard output respectively. +This option can be used for _plain_ device type only. endif::[] - -ifdef::ACTION_TOKEN[] -*--token-replace*:: -Replace an existing token when adding or importing a token with the ---token-id option. +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. +Use _cryptsetup --help_ to show the compiled-in defaults. endif::[] - -ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] -*--use-random*:: -*--use-urandom*:: 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). -+ -See *NOTES ON RANDOM NUMBER GENERATORS* in *cryptsetup*(8) for more -information. Use _cryptsetup --help_ to show the compiled-in default random -number generator. +*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. + -*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::[] +If there is not enough space for keyslots with new key size, +you can destructively shrink device with --reduce-device-size option. endif::[] - -ifdef::ACTION_REENCRYPT[] -*--keep-key*:: -*LUKS2*: -Do not change effective volume key and change other parameters provided -it is requested. -+ -*LUKS1*: -Reencrypt only the LUKS1 header and keyslots. Skips data in-place reencryption. 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[] @@ -349,6 +567,90 @@ size and key size, but a valid key slot ID can always be between 0 and 31 for LUKS2. endif::[] +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] +*--keyslot-cipher <cipher-spec>*:: +This option can be used to set specific cipher encryption for the +LUKS2 keyslot area. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] +*--keyslot-key-size <bits>*:: +This option can be used to set specific key size for the LUKS2 keyslot +area. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_CONFIG,ACTION_REENCRYPT[] +*--label <LABEL> --subsystem <SUBSYSTEM>*:: +Set label and subsystem description for LUKS2 device. +The label and subsystem are optional fields and can be later used +in udev scripts for triggering user actions once the device marked +by these labels is detected. +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSRESUME[] +*--link-vk-to-keyring* _<keyring_description>::<key_description>_:: +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). ++ +_<keyring_description>_ string has to contain existing kernel keyring +description. The keyring name may be optionally prefixed with "%:" or "%keyring:" type descriptions. +Or, the keyring may also be specified directly by numeric key id. Also special keyring notations +starting with "@" may be used to select existing predefined kernel keyrings. ++ +The string "::" is delimiter used to separate keyring description and key description. ++ +_<key_description>_ part describes key type and key name of volume key linked in the keyring +described in _<keyring_description>_. The type may be specified by adding "%<type_name>:" prefix in front of +key name. If type is missing default _user_ type is applied. If the key of same name and same type already exists (already linked in the keyring) +it will get replaced in the process. ++ +See also *KEY IDENTIFIERS* section of *keyctl*(1). +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 <size> +can be specified with 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 <size> can be specified with unit suffix (for example 128k). +endif::[] + +ifdef::ACTION_LUKSADDKEY[] +*--new-keyfile* _name_:: +Read the passphrase for a new keyslot from file. ++ +If the name given is "-", then the passphrase will be read from stdin. +In this case, reading will not stop at newline characters. ++ +This is alternative method to positional argument when adding new +passphrase via kefile. +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. +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. The default is to read the whole file up to +the compiled-in maximum length that can be queried with --help. +Supplying more than the compiled in maximum aborts the operation. When +--new-keyfile-offset is also given, reading starts after the offset. +endif::[] + ifdef::ACTION_LUKSADDKEY[] *--new-key-slot <0-N>*:: This option allows you to specify which key slot is selected for @@ -362,48 +664,9 @@ size and key size, but a valid key slot ID can always be between 0 and 31 for LUKS2. endif::[] -ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_BENCHMARK,ACTION_LUKSADDKEY[] -*--key-size, -s* _bits_:: -ifndef::ACTION_LUKSADDKEY[] -Sets key size in _bits_. The argument has to be a multiple of 8. The -possible key-sizes are limited by the cipher and mode used. -+ -See /proc/crypto for more information. Note that key-size in -/proc/crypto is stated in bytes. -+ -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. -endif::[] -ifdef::ACTION_OPEN[] -This option can be used for _plain_ device type only. -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. -Use _cryptsetup --help_ to show the compiled-in defaults. -endif::[] -ifdef::ACTION_REENCRYPT[] -*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 there is not enough space for keyslots with new key size, -you can destructively shrink device with --reduce-device-size option. -endif::[] -endif::[] - -ifdef::ACTION_OPEN,ACTION_RESIZE[] -*--size, -b <number of 512 byte sectors>*:: -Set the size of the device in sectors of 512 bytes. -ifdef::ACTION_OPEN[] -Usable only with _plain_ device type. -endif::[] +*--new-token-id*:: +Specify what token to use to get the passphrase for a new keyslot. endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] @@ -423,55 +686,6 @@ device and must be aligned to 4096-byte sectors (must be multiple of endif::[] endif::[] -ifdef::ACTION_OPEN[] -*--skip, -p <number of 512 byte sectors>*:: -Start offset used in IV calculation in 512-byte sectors (how many -sectors of the encrypted data to skip at the beginning). This option -is only relevant with plain or loopaes device types. -+ -Hence, if --offset _n_, and --skip _s_, sector _n_ (the first sector of -the encrypted device) will get a sector number of _s_ for the IV -calculation. -endif::[] - -ifdef::ACTION_OPEN,ACTION_REENCRYPT,ACTION_RESIZE[] -*--device-size* _size[units]_:: -ifndef::ACTION_RESIZE[] -Instead of real device size, use specified value. -endif::[] -ifdef::ACTION_RESIZE[] -Sets new size of the device. If unset 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. -+ -*WARNING:* This is destructive operation. Data beyond --device-size limit may -be lost after operation gets 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). -endif::[] - -ifdef::ACTION_OPEN[] -*--readonly, -r*:: -set up a read-only mapping. -endif::[] - -ifdef::ACTION_OPEN[] -*--shared*:: -Creates an additional mapping for one common ciphertext device. -Arbitrary mappings are supported. This option is only relevant for the -_plain_ device type. Use --offset, --size and --skip to specify -the mapped area. -endif::[] - ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] *--pbkdf <PBKDF spec>*:: Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS @@ -522,16 +736,11 @@ cost minimum is 1 and maximum 4 (if enough CPUs cores are available, otherwise it is decreased). endif::[] -ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] -*--iter-time, -i <number of milliseconds>*:: -ifndef::ACTION_REENCRYPT[] -The number of milliseconds to spend with PBKDF passphrase processing. -Specifying 0 as 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. -endif::[] +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] +*--pbkdf-force-iterations <num>*:: +Avoid PBKDF benchmark and set time cost (iterations) directly. It can +be used for LUKS/LUKS2 device only. See _--pbkdf_ option for more +info. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] @@ -549,11 +758,63 @@ that it is maximal value, it is decreased automatically if CPU online count is lower. This option is not available for PBKDF2. endif::[] -ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] -*--pbkdf-force-iterations <num>*:: -Avoid PBKDF benchmark and set time cost (iterations) directly. It can -be used for LUKS/LUKS2 device only. See _--pbkdf_ option for more -info. +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. 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. The +default is to use an unbound workqueue so that encryption work is +automatically balanced between available CPUs. ++ +*NOTE:* This option is available only for low-level dm-crypt performance +tuning, use only if you need a change to default dm-crypt behaviour. +Needs kernel 4.0 or later. +endif::[] + +ifdef::ACTION_REFRESH,ACTION_OPEN[] +*--perf-submit_from_crypt_cpus*:: +Disable offloading writes to a separate thread after encryption. There +are some situations where offloading write bios from the encryption +threads to a single thread degrades performance significantly. The +default is to offload write bios to the same thread. ++ +*NOTE:* This option is available only for low-level dm-crypt performance +tuning, use only if you need a change to default dm-crypt behaviour. +Needs kernel 4.0 or later. +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. (No need to use cryptab or other system configuration +files.) ++ +If you need to remove a persistent flag, use _--persistent_ without the +flag you want to remove (e.g. to disable persistently stored discard +flag, use _--persistent_ without _--allow-discards_). ++ +Only _--allow-discards_, _--perf-same_cpu_crypt_, +_--perf-submit_from_crypt_cpus_, _--perf-no_read_workqueue_, +_--perf-no_write_workqueue_ and _--integrity-no-journal_ can be stored +persistently. +endif::[] + +ifdef::ACTION_CONFIG[] +*--priority <normal|prefer|ignore>*:: +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. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] @@ -575,11 +836,11 @@ progress (except it's compact single line): + .... { - "device":"/dev/sda" // backing device or file + "device":"/dev/sda", // backing device or file "device_bytes":"8192", // bytes of I/O so far "device_size":"44040192", // total bytes of I/O to go "speed":"126877696", // calculated speed in bytes per second (based on progress so far) - "eta_ms":"2520012" // estimated time to finish an operation in milliseconds + "eta_ms":"2520012", // estimated time to finish an operation in milliseconds "time_ms":"5561235" // total time spent in IO operation in milliseconds } .... @@ -589,283 +850,193 @@ numbers are represented in a string format due to need of full 64bit unsigned integers. 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 <number of seconds>*:: -The number of seconds to wait before timeout on passphrase input via -terminal. It is relevant every time a passphrase is asked. -It has no effect if used in conjunction with --key-file. -+ -This option is useful when the system should not stall if the user -does not input a passphrase, e.g. during boot. The default is a value -of 0 seconds, which means to wait forever. -endif::[] - -ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_REENCRYPT[] -*--tries, -T*:: -How often the input of the passphrase shall be retried. The default is 3 tries. +ifdef::ACTION_OPEN[] +*--readonly, -r*:: +set up a read-only mapping. endif::[] -ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] -*--align-payload <number of 512 byte sectors>*:: -Align payload at a boundary of _value_ 512-byte sectors. +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. + -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). +It could be useful if you added some space to underlying partition or +logical volume (so last _size_ sectors contains no data). + -For a detached LUKS header, this option specifies the offset on the data -device. See also the --header option. +For units suffix see --device-size parameter description. + -*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. -endif::[] - -ifdef::ACTION_LUKSFORMAT,ACTION_LUKSUUID,ACTION_REENCRYPT[] -*--uuid <UUID>*:: -ifndef::ACTION_REENCRYPT[] -Use the provided _UUID_ for the _luksFormat_ command instead of -generating a new one. Changes the existing _UUID_ when used with the -_luksUUID_ command. +*WARNING:* This is a destructive operation and cannot be reverted. Use +with extreme care - accidentally overwritten filesystems are usually +unrecoverable. + -endif::[] -ifdef::ACTION_REENCRYPT[] -When used in encryption mode use the provided _UUID_ for the new LUKS header -instead of generating a new one. +*LUKS2*: +Initialize LUKS2 reencryption with data device size reduction +(currently only encryption mode is supported). + -*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. +Recommended minimal size is twice the default LUKS2 header size +(--reduce-device-size 32M) for encryption mode. ++ +*LUKS1*: +Enlarge data offset to specified value by shrinking device size. + +You cannot shrink device more than by 64 MiB (131072 sectors). endif::[] -The _UUID_ must be provided in the standard UUID format, e.g. -12345678-1234-1234-1234-123456789abc. + +ifdef::ACTION_OPEN[] +*--refresh*:: +Refreshes an active device with new set of parameters. See +*cryptsetup-refresh*(8) for more details. endif::[] -ifdef::ACTION_OPEN,ACTION_REFRESH[] -*--allow-discards*:: -Allow the use of discard (TRIM) requests for the device. This is also not -supported for LUKS2 devices with data integrity protection. +ifdef::ACTION_REENCRYPT[] +*--resilience* _mode_ *(LUKS2 only)*:: +Reencryption resilience _mode_ can be one of _checksum_, _journal_ or +_none_. + -*WARNING:* This command can have a negative security impact because it -can make filesystem-level operations visible on the physical device. For -example, information leaking filesystem type, used space, etc. may be -extractable from the physical device if the discarded blocks can be -located later. If in doubt, do not use it. +_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. + -A kernel version of 3.1 or later is needed. For earlier kernels, this -option is ignored. -endif::[] - -ifdef::ACTION_REFRESH,ACTION_OPEN[] -*--perf-same_cpu_crypt*:: -Perform encryption using the same cpu that IO was submitted on. The -default is to use an unbound workqueue so that encryption work is -automatically balanced between available CPUs. +_journal_: the hotzone is journaled in the binary area (so the data are +written twice). + -*NOTE:* This option is available only for low-level dm-crypt performance -tuning, use only if you need a change to default dm-crypt behaviour. -Needs kernel 4.0 or later. -endif::[] - -ifdef::ACTION_REFRESH,ACTION_OPEN[] -*--perf-submit_from_crypt_cpus*:: -Disable offloading writes to a separate thread after encryption. There -are some situations where offloading write bios from the encryption -threads to a single thread degrades performance significantly. The -default is to offload write bios to the same thread. +_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. + -*NOTE:* This option is available only for low-level dm-crypt performance -tuning, use only if you need a change to default dm-crypt behaviour. -Needs kernel 4.0 or later. +Resilience modes can be changed unless _datashift_ mode is used for +operation initialization (encryption with --reduce-device-size option) endif::[] -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. Needs kernel 5.9 or later. +ifdef::ACTION_REENCRYPT[] +*--resilience-hash* _hash_ *(LUKS2 only)*:: +The _hash_ algorithm used with "--resilience checksum" only. The default +hash is sha256. With other resilience modes, the hash parameter is +ignored. endif::[] -ifdef::ACTION_OPEN[] -*--test-passphrase*:: -Do not activate the device, just verify passphrase. The device mapping name is -not mandatory if this option is used. +ifdef::ACTION_REENCRYPT[] +*--resume-only (LUKS2 only)*:: +Resume reencryption (any mode) operation 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. endif::[] -ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP[] -*--header <device or file storing the LUKS 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. -+ +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +ifndef::ACTION_REENCRYPT[] +*--sector-size* _bytes_:: endif::[] +ifndef::ACTION_REENCRYPT[] ifdef::ACTION_OPEN[] -Specify detached (separated) metadata device or file where the header is stored. +Set encryption sector size for use with _plain_ device type. It must be power of two +and in range 512 - 4096 bytes. The default mode is 512 bytes. + -*WARNING:* There is no check whether the ciphertext device specified -actually belongs to the header given. In fact, you can specify an -arbitrary device as the ciphertext device with the --header option. -Use with care. +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. endif::[] -ifndef::ACTION_REENCRYPT[] 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. +Set sector size for use with disk encryption. It must be power of two +and in range 512 - 4096 bytes. This option is available only with LUKS2 +format. + -The --align-payload option is taken as absolute sector alignment on 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. -endif::[] -endif::[] -ifdef::ACTION_REENCRYPT[] -If used with --encrypt/--new option, the header file will be created (or overwritten). -Use with care. +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. + -*LUKS2*: -For decryption mode the option may be used to export 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. +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. + -*WARNING:* Never put exported header file in a filesystem on top of 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. -endif::[] -endif::[] - -ifdef::ACTION_LUKSHEADERBACKUP,ACTION_LUKSHEADERRESTORE[] -*--header-backup-file <file>*:: -Specify file with header backup file. -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. This option enables both SW and HW based data encryption. +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). 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. ++ +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[] -*--force-offline-reencrypt (LUKS2 only)*:: -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. +*--sector-size* _bytes_ *(LUKS2 only)*:: +Reencrypt device with new encryption sector size enforced. + -*WARNING:* Use with extreme caution! This may destroy data if the device -is activated and/or actively used. +*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. +endif::[] endif::[] -ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] -*--force-password*:: -Do not use password quality checking for new LUKS passwords. +ifdef::ACTION_OPEN[] +*--serialize-memory-hard-pbkdf*:: +Use a global lock to serialize unlocking of keyslots using memory-hard +PBKDF. + -This option is ignored if cryptsetup is built without password -quality checking support. +*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. + -For more info about password quality check, see the manual page for -*pwquality.conf(5)* and *passwdqc.conf(5)*. +*DO NOT USE* this switch until you are implementing boot environment +with parallel devices activation! endif::[] -ifdef::ACTION_CLOSE[] -*--deferred*:: -Defers device removal in _close_ command until the last user closes -it. +ifdef::ACTION_OPEN[] +*--shared*:: +Creates an additional mapping for one common ciphertext device. +Arbitrary mappings are supported. This option is only relevant for the +_plain_ device type. Use --offset, --size and --skip to specify +the mapped area. endif::[] -ifdef::ACTION_CLOSE[] -*--cancel-deferred*:: -Removes a previously configured deferred device removal in _close_ -command. +ifdef::ACTION_OPEN,ACTION_RESIZE[] +*--size, -b <number of 512 byte sectors>*:: +Set the size of the device in sectors of 512 bytes. +ifdef::ACTION_OPEN[] +Usable only with _plain_ device type. endif::[] - -ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] -*--disable-blkid*:: -Disable use of blkid library for checking and wiping on-disk signatures. endif::[] -ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_RESIZE,ACTION_TOKEN[] -*--disable-external-tokens*:: -Disable loading of plugins for external LUKS2 tokens. -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. -+ -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. +ifdef::ACTION_OPEN[] +*--skip, -p <number of 512 byte sectors>*:: +Start offset used in IV calculation in 512-byte sectors (how many +sectors of the encrypted data to skip at the beginning). This option +is only relevant with plain or loopaes device types. + -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). +Hence, if --offset _n_, and --skip _s_, sector _n_ (the first sector of +the encrypted device) will get a sector number of _s_ for the IV +calculation. 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. This option is supported only for the LUKS2 type. +ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] +*--tcrypt-backup*:: +*--tcrypt-hidden*:: +*--tcrypt-system*:: +Specify which TrueCrypt on-disk +header will be used to open the device. See _TCRYPT_ section in +*cryptsetup*(8) for more info. endif::[] -ifdef::ACTION_TOKEN[] -*--key-description <text>*:: -Set key description in keyring for use with _token_ command. +ifdef::ACTION_OPEN[] +*--test-passphrase*:: +Do not activate the device, just verify passphrase. The device mapping name is +not mandatory if this option is used. endif::[] -ifdef::ACTION_OPEN,ACTION_LUKSRESUME[] -*--link-vk-to-keyring* _<keyring_description>::<key_description>_:: -Link volume key in a keyring with specified key name. The volume key is linked only -if requested action is successfully finished. -+ -_<keyring_description>_ string has to contain existing kernel keyring -description. The keyring name may be optionally prefixed with "%:" or "%keyring:" type descriptions. -Or, the keyring may also be specified directly by numeric key id. Also special keyring notations -starting with "@" may be used to select existing predefined kernel keyrings. -+ -The string "::" is delimiter used to separate keyring description and key description. -+ -_<key_description>_ part describes key type and key name of volume key linked in the keyring -described in _<keyring_description>_. The type may be specified by adding "%<type_name>:" 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. +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 <number of seconds>*:: +The number of seconds to wait before timeout on passphrase input via +terminal. It is relevant every time a passphrase is asked. +It has no effect if used in conjunction with --key-file. + -See also *KEY IDENTIFIERS* section of *keyctl*(1). -endif::[] - -ifdef::ACTION_CONFIG[] -*--priority <normal|prefer|ignore>*:: -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. +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::[] ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_LUKSADDKEY[] @@ -884,11 +1055,6 @@ new token. endif::[] endif::[] -ifdef::ACTION_LUKSADDKEY[] -*--new-token-id*:: -Specify what token to use to get the passphrase for a new keyslot. -endif::[] - ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[] *--token-only*:: ifndef::ACTION_LUKSADDKEY[] @@ -905,6 +1071,12 @@ Use only LUKS2 tokens to unlock existing volume key. endif::[] endif::[] +ifdef::ACTION_TOKEN[] +*--token-replace*:: +Replace an existing token when adding or importing a token with the +--token-id option. +endif::[] + ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[] *--token-type* _type_:: ifndef::ACTION_LUKSADDKEY[] @@ -919,193 +1091,101 @@ Specify what token type (all _type_ tokens) to use when unlocking existing keysl endif::[] endif::[] -ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] -ifndef::ACTION_REENCRYPT[] -*--sector-size* _bytes_:: + +ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_REENCRYPT[] +*--tries, -T*:: +How often the input of the passphrase shall be retried. The default is 3 tries. 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 <device-type>*:: 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. 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. -endif::[] -ifdef::ACTION_LUKSFORMAT[] -Set sector size for use with disk encryption. It must be power of two -and in range 512 - 4096 bytes. This option is available only with LUKS2 -format. -+ -For LUKS2 devices it's established based on parameters provided by -underlying data device. For native 4K block devices it's 4096 bytes. -For 4K/512e (4K physical sector size with 512 bytes emulation) it's -4096 bytes. For drives reporting only 512 bytes block size it remains -512 bytes. If data device is regular file put in filesystem it's 4096 -bytes. -+ -Note that if sector size is higher than underlying device hardware -sector and there is not integrity protection that uses data journal, -using this option can increase risk on incomplete sector writes during a -power fail. -+ -If used together with _--integrity_ option and dm-integrity journal, the -atomicity of writes is guaranteed in all cases (but it cost write -performance - data has to be written twice). -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. +Specifies required device type, for more info read _BASIC ACTIONS_ section in *cryptsetup*(8). endif::[] ifdef::ACTION_REENCRYPT[] -*--sector-size* _bytes_ *(LUKS2 only)*:: -Reencrypt device with 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. +Specifies required (encryption mode) or expected (other modes) LUKS format. Accepts only _luks1_ or _luks2_. endif::[] 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. -+ -*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. +ifdef::ACTION_OPEN,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_TOKEN[] +*--unbound*:: +ifdef::ACTION_LUKSADDKEY[] +Creates new LUKS2 unbound keyslot. 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. (No need to use cryptab or other system configuration -files.) -+ -If you need to remove a persistent flag, use _--persistent_ without the -flag you want to remove (e.g. to disable persistently stored discard -flag, use _--persistent_ without _--allow-discards_). -+ -Only _--allow-discards_, _--perf-same_cpu_crypt_, -_--perf-submit_from_crypt_cpus_, _--perf-no_read_workqueue_, -_--perf-no_write_workqueue_ and _--integrity-no-journal_ can be stored -persistently. +ifdef::ACTION_LUKSDUMP[] +Dumps existing LUKS2 unbound keyslot. endif::[] - ifdef::ACTION_OPEN[] -*--refresh*:: -Refreshes an active device with new set of parameters. See -*cryptsetup-refresh*(8) for more details. +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. +endif::[] +ifdef::ACTION_TOKEN[] +Creates new LUKS2 keyring token assigned to no keyslot. Usable only with _add_ action. endif::[] - -ifdef::ACTION_LUKSFORMAT,ACTION_CONFIG,ACTION_REENCRYPT[] -*--label <LABEL> --subsystem <SUBSYSTEM>*:: -Set label and subsystem description for LUKS2 device. -The label and subsystem are optional fields and can be later used -in udev scripts for triggering user actions once the device marked -by these labels is detected. endif::[] -ifdef::ACTION_LUKSFORMAT[] -*--integrity <integrity algorithm>*:: -Specify integrity algorithm to be used for authenticated disk -encryption in LUKS2. -+ -*WARNING: This extension is EXPERIMENTAL* and requires dm-integrity -kernel target (available since kernel version 4.12). For native AEAD -modes, also enable "User-space interface for AEAD cipher algorithms" in -"Cryptographic API" section (CONFIG_CRYPTO_USER_API_AEAD .config -option). -+ -For more info, see _AUTHENTICATED DISK ENCRYPTION_ section in *cryptsetup*(8). +ifdef::COMMON_OPTIONS[] +*--usage*:: +Show short option help. endif::[] -ifdef::ACTION_LUKSFORMAT[] -*--integrity-legacy-padding*:: -Use inefficient legacy padding. +ifdef::ACTION_REENCRYPT[] +*--use-directio (LUKS1 only)*:: +Use direct-io (O_DIRECT) for all read/write data operations related +to block device undergoing reencryption. + -*WARNING*: Do not use this option until you need compatibility with specific -old kernel. +Useful if direct-io operations perform better than normal buffered +operations (e.g. in virtual environments). 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 <size> can be specified with unit suffix (for example 128k). +ifdef::ACTION_REENCRYPT[] +*--use-fsync (LUKS1 only)*:: +Use fsync call after every written block. This applies for reencryption +log files as well. 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 <size> -can be specified with unit suffix (for example 128k). -endif::[] - -ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] -*--keyslot-cipher <cipher-spec>*:: -This option can be used to set specific cipher encryption for the -LUKS2 keyslot area. +*--use-random*:: +*--use-urandom*:: +ifdef::ACTION_REENCRYPT[] +Define which kernel random number generator will be used to create the volume key. endif::[] - -ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[] -*--keyslot-key-size <bits>*:: -This option can be used to set specific key size for the LUKS2 keyslot -area. +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). ++ +See *NOTES ON RANDOM NUMBER GENERATORS* in *cryptsetup*(8) for more +information. Use _cryptsetup --help_ to show the compiled-in default random +number generator. ++ +*WARNING:* In a low-entropy situation (e.g. in an embedded system) and older +kernels, both selections are problematic. Using /dev/urandom can lead to weak keys. +Using /dev/random can block a long time, potentially forever, if not +enough entropy can be harvested by the kernel. 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. 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. +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSUUID,ACTION_REENCRYPT[] +*--uuid <UUID>*:: +ifndef::ACTION_REENCRYPT[] +Use the provided _UUID_ for the _luksFormat_ command instead of +generating a new one. Changes the existing _UUID_ when used with the +_luksUUID_ command. + -*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. -endif::[] - -ifdef::ACTION_OPEN,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_TOKEN[] -*--unbound*:: -ifdef::ACTION_LUKSADDKEY[] -Creates new LUKS2 unbound keyslot. -endif::[] -ifdef::ACTION_LUKSDUMP[] -Dumps 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. -endif::[] -ifdef::ACTION_TOKEN[] -Creates new LUKS2 keyring token assigned to no keyslot. Usable only with _add_ action. endif::[] +ifdef::ACTION_REENCRYPT[] +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. ++ endif::[] - -ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] -*--tcrypt-hidden*:: -*--tcrypt-system*:: -*--tcrypt-backup*:: -Specify which TrueCrypt on-disk -header will be used to open the device. See _TCRYPT_ section in -*cryptsetup*(8) for more info. +The _UUID_ must be provided in the standard UUID format, e.g. +12345678-1234-1234-1234-123456789abc. endif::[] ifdef::ACTION_TCRYPTDUMP,ACTION_OPEN[] @@ -1115,158 +1195,80 @@ default. endif::[] ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] -*--disable-veracrypt*:: -This option can be used to disable VeraCrypt compatible mode (only -TrueCrypt devices are recognized). Only for TCRYPT extension. See -_TCRYPT_ section in *cryptsetup*(8) for more info. -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. endif::[] -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. -+ -*DO NOT USE* this switch until you are implementing boot environment -with parallel devices activation! +ifdef::ACTION_ISLUKS[] +*--verbose, -v*:: +Print more information on command execution. endif::[] -ifdef::ACTION_REENCRYPT[] -*--encrypt, --new, -N*:: -Initialize (and run) device in-place encryption mode. +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_REPAIR,ACTION_TCRYPTDUMP,ACTION_REENCRYPT[] +*--verify-passphrase, -y*:: +When interactively asking for a passphrase, ask for it twice and +complain if both inputs do not match. +ifdef::ACTION_OPEN[] +Advised when creating a _plain_ type mapping for the first time. endif::[] - -ifdef::ACTION_REENCRYPT[] -*--decrypt*:: -Initialize (and run) device decryption mode. +Ignored on input from file or stdin. endif::[] -ifdef::ACTION_REENCRYPT[] -*--init-only (LUKS2 only)*:: -Initialize reencryption (any mode) operation in LUKS2 metadata only -and exit. If any reencrypt operation is already initialized in -metadata, the command with --init-only parameter fails. +ifdef::COMMON_OPTIONS[] +*--version, -V*:: +Show the program version. endif::[] -ifdef::ACTION_REENCRYPT[] -*--resume-only (LUKS2 only)*:: -Resume reencryption (any mode) operation 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. +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_BITLKDUMP,ACTION_REENCRYPT[] +*--volume-key-file, --master-key-file (OBSOLETE alias)*:: +ifndef::ACTION_REENCRYPT[] +Use a volume key stored in a file. endif::[] - -ifdef::ACTION_REENCRYPT[] -*--resilience* _mode_ *(LUKS2 only)*:: -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). -+ -_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. +ifdef::ACTION_FORMAT[] + -Resilience modes can be changed unless _datashift_ mode is used for -operation initialization (encryption with --reduce-device-size option) +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. + endif::[] - -ifdef::ACTION_REENCRYPT[] -*--resilience-hash* _hash_ *(LUKS2 only)*:: -The _hash_ algorithm used with "--resilience checksum" only. The default -hash is sha256. With other resilience modes, the hash parameter is -ignored. +ifdef::ACTION_LUKSDUMP,ACTION_BITLKDUMP[] +The volume key is stored in a file instead of being printed out to standard output. + 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 <size> due to other limitations (free space in keyslots -area or available memory). +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. + -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. endif::[] - +ifdef::ACTION_OPEN[] +This allows one to open _luks_ and _bitlk_ device types without giving a passphrase. + +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. -+ -It could be useful if you added some space to underlying partition or -logical volume (so last _size_ sectors contains no data). -+ -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). -+ -Recommended minimal size is twice the default LUKS2 header size -(--reduce-device-size 32M) for encryption mode. -+ -*LUKS1*: -Enlarge data offset to specified value by shrinking device size. -+ -You cannot shrink device more than by 64 MiB (131072 sectors). +Use (set) new volume key stored in a file. + endif::[] - -ifdef::ACTION_RESIZE,ACTION_OPEN,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_LUKSRESUME,ACTION_TOKEN[] -*--external-tokens-path* _absolute_path_:: -Override system directory path where cryptsetup searches for external token -handlers (or token plugins). It must be absolute path (starting with '/' character). +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_REENCRYPT[] +*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. endif::[] - -ifdef::COMMON_OPTIONS[] -*--batch-mode, -q*:: -Suppresses all confirmation questions. Use with care! -+ -If the --verify-passphrase option is not specified, this option also -switches off the passphrase verification. endif::[] -ifdef::COMMON_OPTIONS[] -*--debug or --debug-json*:: -Run in debug mode with full diagnostic logs. Debug output lines are -always prefixed by *#*. +ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[] +*--volume-key-keyring* _<key description>_:: +Use a volume key stored in a keyring. +This allows one to open _luks_ and device types without giving a passphrase. +The key and associated type has to be readable from userspace so that volume +key digest may be verified in before activation. + -If --debug-json is used, additional LUKS2 JSON data structures are printed. -endif::[] - -ifdef::COMMON_OPTIONS[] -*--version, -V*:: -Show the program version. -endif::[] - -ifdef::COMMON_OPTIONS[] -*--usage*:: -Show short option help. +The _<key description>_ uses keyctl-compatible syntax. This can either be a +numeric key ID or a string name in the format _%<key type>:<key name>_. See +also *KEY IDENTIFIERS* section of *keyctl*(1). When no _%<key type>:_ prefix +is specified we assume the key type is _user_ (default type). endif::[] -ifdef::COMMON_OPTIONS[] -*--help, -?*:: -Show help text and default parameters. +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. endif::[] diff --git a/man/cryptsetup-ssh.8.adoc b/man/cryptsetup-ssh.8.adoc index f71f856..d2c2c06 100644 --- a/man/cryptsetup-ssh.8.adoc +++ b/man/cryptsetup-ssh.8.adoc @@ -37,6 +37,15 @@ required for this operation. == OPTIONS +*--debug*:: +Show debug messages + +*--debug-json*:: +Show debug messages including JSON metadata + +*--help, -?*:: +Show help + **--key-slot**=_NUM_:: Keyslot to assign the token to. If not specified, the token will be assigned to the first key slot matching provided passphrase. @@ -53,18 +62,9 @@ IP address/URL of the remote server for this token. **--ssh-user**=_STRING_:: Username used for the remote server. -*--debug*:: -Show debug messages - -*--debug-json*:: -Show debug messages including JSON metadata - *--verbose, -v*:: Shows more detailed error messages -*--help, -?*:: -Show help - *--version, -V*:: Print program version diff --git a/man/integritysetup.8.adoc b/man/integritysetup.8.adoc index e89b0f7..26b957c 100644 --- a/man/integritysetup.8.adoc +++ b/man/integritysetup.8.adoc @@ -89,72 +89,33 @@ kernel version 5.7, shrinking should work on older kernels too. *<options>* can be [--size, --device-size, --wipe]. == OPTIONS -*--progress-frequency <seconds>*:: -Print separate line every <seconds> 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): -+ -.... -{ - "device":"/dev/sda" // backing device or file - "device_bytes":"8192", // bytes wiped so far - "device_size":"44040192", // total bytes to wipe - "speed":"126877696", // calculated speed in bytes per second (based on progress so far) - "eta_ms":"2520012" // estimated time to finish wipe in milliseconds - "time_ms":"5561235" // total time spent wiping device in milliseconds -} -.... -+ -Note on numbers in JSON output: Due to JSON parsers limitations all -numbers are represented in a string format due to need of full 64bit -unsigned integers. - -*--no-wipe*:: -Do not wipe the device after format. A device that is not initially -wiped will contain invalid checksums. - -*--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. - -*--journal-size, -j BYTES*:: -Size of the journal. - -*--interleave-sectors SECTORS*:: -The number of interleaved sectors. - -*--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. This option is available since the Linux kernel version -4.19. +*--allow-discards*:: +Allow the use of discard (TRIM) requests for the device. This option +is available since the Linux kernel version 5.7. -*--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. This option is available since the Linux kernel version -5.13. +*--batch-mode, -q*:: +Do not ask for confirmation. -*--journal-watermark PERCENT*:: -Journal watermark in percents. When the size of the journal exceeds -this watermark, the journal flush will be started. +*--bitmap-flush-time MS*:: +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. -*--journal-commit-time MS*:: -Commit time in milliseconds. When this time passes (and no explicit -flush operation was issued), the journal is written. +*--bitmap-sectors-per-bit SECTORS*:: +Number of 512-byte sectors per bitmap bit, the value must be power of +two. -*--tag-size, -t BYTES*:: -Size of the integrity tag per-sector (here the integrity function will -store authentication tag). +*--buffer-sectors SECTORS*:: +The number of sectors in one buffer. + -*NOTE:* The size can be smaller that output size of the hash function, -in that case only part of the hash will be stored. +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. + +*--cancel-deferred*:: +Removes a previously configured deferred device removal in *close* +command. *--data-device <data_device>*:: Specify a separate data device that contains existing data. The @@ -165,14 +126,16 @@ data on <data_device>. --no-wipe option and activate with --integrity-recalculate to automatically recalculate integrity tags. -*--sector-size, -s BYTES*:: -Sector size (power of two: 512, 1024, 2048, 4096). +*--debug*:: +Run in debug mode with full diagnostic logs. Debug output lines are +always prefixed by *#*. -*--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. +*--deferred*:: +Defers device removal in *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 @@ -182,15 +145,6 @@ algorithm can be CRC (crc32c/crc32), non-cryptographic hash function For HMAC (hmac-sha256) you have also to specify an integrity key and its size. -*--integrity-key-size BYTES*:: -The size of the data integrity key. Maximum is 4096 bytes. - -*--integrity-key-file FILE*:: -The file with the integrity key. - -*--integrity-no-journal, -D*:: -Disable journal for integrity device. - *--integrity-bitmap-mode. -B*:: Use alternate bitmap mode (available since Linux kernel 5.2) where dm-integrity uses bitmap instead of a journal. If a bit in the bitmap @@ -201,76 +155,120 @@ 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. -*--bitmap-sectors-per-bit SECTORS*:: -Number of 512-byte sectors per bitmap bit, the value must be power of -two. +*--integrity-key-file FILE*:: +The file with the integrity key. -*--bitmap-flush-time MS*:: -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. +*--integrity-key-size BYTES*:: +The size of the data integrity key. Maximum is 4096 bytes. -*--integrity-recovery-mode. -R*:: -Recovery mode (no journal, no tag checking). +*--integrity-no-journal, -D*:: +Disable journal for integrity device. -*NOTE:* The following options are intended for testing purposes only.: -Using journal encryption does not make sense without encryption the -data, these options are internally used in authenticated disk -encryption with *cryptsetup(8)*. +*--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. This option is available since the Linux kernel version +4.19. -*--journal-integrity ALGORITHM*:: -Integrity algorithm for journal area. See --integrity option for -detailed specification. +*--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. This option is available since the Linux kernel version +5.13. -*--journal-integrity-key-size BYTES*:: -The size of the journal integrity key. Maximum is 4096 bytes. +*--integrity-recovery-mode. -R*:: +Recovery mode (no journal, no tag checking). -*--journal-integrity-key-file FILE*:: -The file with the integrity key. +*--interleave-sectors SECTORS*:: +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. *--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. ++ +*NOTE:* The journal encryption options are only intended for testing. +Using journal encryption does not make sense without encryption of the data. + +*--journal-crypt-key-file FILE*:: +The file with the journal encryption key. *--journal-crypt-key-size BYTES*:: The size of the journal encryption key. Maximum is 4096 bytes. -*--journal-crypt-key-file FILE*:: -The file with the journal encryption key. +*--journal-integrity ALGORITHM*:: +Integrity algorithm for journal area. See --integrity option for +detailed specification. -*--allow-discards*:: -Allow the use of discard (TRIM) requests for the device. This option -is available since the Linux kernel version 5.7. +*--journal-integrity-key-file FILE*:: +The file with the integrity key. -*--deferred*:: -Defers device removal in *close* command until the last user closes -it. +*--journal-integrity-key-size BYTES*:: +The size of the journal integrity key. Maximum is 4096 bytes. -*--cancel-deferred*:: -Removes a previously configured deferred device removal in *close* -command. +*--journal-size, -j BYTES*:: +Size of the journal. -*--verbose, -v*:: -Print more information on command execution. +*--journal-watermark PERCENT*:: +Journal watermark in percents. When the size of the journal exceeds +this watermark, the journal flush will be started. -*--debug*:: -Run in debug mode with full diagnostic logs. Debug output lines are -always prefixed by *#*. +*--no-wipe*:: +Do not wipe the device after format. A device that is not initially +wiped will contain invalid checksums. -*--version, -V*:: -Show the program version. +*--progress-frequency <seconds>*:: +Print separate line every <seconds> with wipe progress. -*--batch-mode, -q*:: -Do not ask for confirmation. +*--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): ++ +.... +{ + "device":"/dev/sda", // backing device or file + "device_bytes":"8192", // bytes wiped so far + "device_size":"44040192", // total bytes to wipe + "speed":"126877696", // calculated speed in bytes per second (based on progress so far) + "eta_ms":"2520012", // estimated time to finish wipe in milliseconds + "time_ms":"5561235" // total time spent wiping device in milliseconds +} +.... ++ +Note on numbers in JSON output: Due to JSON parsers limitations all +numbers are represented in a string format due to need of full 64bit +unsigned integers. + +*--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). ++ +*NOTE:* The size can be smaller that output size of the hash function, +in that case only part of the hash will be stored. *--usage*:: Show short option help. -*--help, -?*:: -Show help text and default parameters. +*--verbose, -v*:: +Print more information on command execution. + +*--version, -V*:: +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. == LEGACY COMPATIBILITY OPTIONS diff --git a/man/veritysetup.8.adoc b/man/veritysetup.8.adoc index 36d1501..d6a1aba 100644 --- a/man/veritysetup.8.adoc +++ b/man/veritysetup.8.adoc @@ -109,59 +109,12 @@ Reports parameters of verity device from on-disk stored superblock. *<options>* can be [--hash-offset]. == OPTIONS +*--batch-mode, -q*:: +Do not ask for confirmation. -*--no-superblock*:: -Create or use dm-verity without permanent on-disk superblock. - -*--format=number*:: -Specifies the hash version type. Format type 0 is original Chrome OS -version. Format type 1 is current version. - -*--data-block-size=bytes*:: -Used block size for the data device. (Note kernel supports only -page-size as maximum here.) - -*--hash-block-size=bytes*:: -Used block size for the hash device. (Note kernel supports only -page-size as maximum here.) - -*--data-blocks=blocks*:: -Size of data device used in verification. If not specified, the whole -device is used. - -*--hash-offset=bytes*:: -Offset of hash area/superblock on hash_device. Value must be aligned -to disk sector offset. - -*--salt=hex string*:: -Salt used for format or verification. Format is a hexadecimal string. - -*--uuid=UUID*:: -Use the provided UUID for format command instead of generating new -one. -+ -The UUID must be provided in standard UUID format, e.g. -12345678-1234-1234-1234-123456789abc. -*--ignore-corruption , --restart-on-corruption , ---panic-on-corruption*:: -Defines what to do if data integrity problem is detected (data -corruption). -+ -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.) -+ -*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. -+ -*WARNING:* Use this option only in very specific cases. This option is -available since Linux kernel version 4.5. +*--cancel-deferred*:: +Removes a previously configured deferred device removal in *close* +command. *--check-at-most-once*:: Instruct kernel to verify blocks only the first time they are read @@ -171,8 +124,21 @@ from the data device, rather than every time. tampering of the data device's content will be detected, not online tampering. This option is available since Linux kernel version 4.17. -*--hash=hash*:: -Hash algorithm for dm-verity. For default see --help option. +*--data-blocks=blocks*:: +Size of 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.) + +*--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. *--fec-device=fec_device*:: Use forward error correction (FEC) to recover from corruption if hash @@ -205,6 +171,47 @@ Number of generator roots. This equals to 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). +*--format=number*:: +Specifies the hash version type. Format type 0 is original Chrome OS +version. Format type 1 is current version. + +*--hash=hash*:: +Hash algorithm for dm-verity. 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.) + +*--hash-offset=bytes*:: +Offset of hash area/superblock on hash_device. Value must be aligned +to 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). ++ +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.) ++ +*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. ++ +*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. + *--root-hash-file=FILE*:: Path to file with stored root hash in hex-encoded text. @@ -213,37 +220,29 @@ 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. +*--salt=hex string*:: +Salt used for format or verification. Format is a hexadecimal string. + +*--usage*:: +Show short option help. + *--use-tasklets*:: Try to use kernel tasklets in dm-verity driver for performance reasons. This option is available since Linux kernel version 6.0. -*--deferred*:: -Defers device removal in *close* command until the last user closes -it. - -*--cancel-deferred*:: -Removes a previously configured deferred device removal in *close* -command. +*--uuid=UUID*:: +Use the provided UUID for format command instead of generating new +one. ++ +The UUID must be provided in standard UUID format, e.g. +12345678-1234-1234-1234-123456789abc. *--verbose, -v*:: Print more information on command execution. -*--debug*:: -Run in debug mode with full diagnostic logs. Debug output lines are -always prefixed by *#*. - *--version, -V*:: Show the program version. -*--batch-mode, -q*:: -Do not ask for confirmation. - -*--usage*:: -Show short option help. - -*--help, -?*:: -Show help text and default parameters. - == RETURN CODES Veritysetup returns *0* on success and a non-zero value on error. |