diff options
Diffstat (limited to 'man')
35 files changed, 4156 insertions, 0 deletions
diff --git a/man/Makemodule.am b/man/Makemodule.am new file mode 100644 index 0000000..41e21da --- /dev/null +++ b/man/Makemodule.am @@ -0,0 +1,145 @@ +ADOCFILES_COMMON = \ + man/common_options.adoc \ + man/common_footer.adoc + +ADOCFILES = $(ADOCFILES_COMMON) \ + man/cryptsetup.8.adoc \ + man/cryptsetup-open.8.adoc \ + man/cryptsetup-close.8.adoc \ + man/cryptsetup-reencrypt.8.adoc \ + man/cryptsetup-status.8.adoc \ + man/cryptsetup-resize.8.adoc \ + man/cryptsetup-refresh.8.adoc \ + man/cryptsetup-luksFormat.8.adoc \ + man/cryptsetup-luksSuspend.8.adoc \ + man/cryptsetup-luksResume.8.adoc \ + man/cryptsetup-luksAddKey.8.adoc \ + man/cryptsetup-luksRemoveKey.8.adoc \ + man/cryptsetup-luksConvertKey.8.adoc \ + man/cryptsetup-luksKillSlot.8.adoc \ + man/cryptsetup-luksChangeKey.8.adoc \ + man/cryptsetup-erase.8.adoc \ + man/cryptsetup-luksUUID.8.adoc \ + man/cryptsetup-isLuks.8.adoc \ + man/cryptsetup-luksDump.8.adoc \ + man/cryptsetup-luksHeaderBackup.8.adoc \ + man/cryptsetup-luksHeaderRestore.8.adoc \ + man/cryptsetup-token.8.adoc \ + man/cryptsetup-convert.8.adoc \ + man/cryptsetup-config.8.adoc \ + man/cryptsetup-tcryptDump.8.adoc \ + man/cryptsetup-bitlkDump.8.adoc \ + man/cryptsetup-fvault2Dump.8.adoc \ + man/cryptsetup-repair.8.adoc \ + man/cryptsetup-benchmark.8.adoc \ + man/cryptsetup-ssh.8.adoc \ + man/veritysetup.8.adoc \ + man/integritysetup.8.adoc + +dist_noinst_DATA += $(ADOCFILES) + +CRYPTSETUP_MANPAGES = \ + man/cryptsetup.8 \ + man/cryptsetup-open.8 \ + man/cryptsetup-close.8 \ + man/cryptsetup-reencrypt.8 \ + man/cryptsetup-status.8 \ + man/cryptsetup-resize.8 \ + man/cryptsetup-refresh.8 \ + man/cryptsetup-luksFormat.8 \ + man/cryptsetup-luksSuspend.8 \ + man/cryptsetup-luksResume.8 \ + man/cryptsetup-luksAddKey.8 \ + man/cryptsetup-luksRemoveKey.8 \ + man/cryptsetup-luksConvertKey.8 \ + man/cryptsetup-luksKillSlot.8 \ + man/cryptsetup-luksChangeKey.8 \ + man/cryptsetup-erase.8 \ + man/cryptsetup-luksUUID.8 \ + man/cryptsetup-isLuks.8 \ + man/cryptsetup-luksDump.8 \ + man/cryptsetup-luksHeaderBackup.8 \ + man/cryptsetup-luksHeaderRestore.8 \ + man/cryptsetup-token.8 \ + man/cryptsetup-convert.8 \ + man/cryptsetup-config.8 \ + man/cryptsetup-tcryptDump.8 \ + man/cryptsetup-bitlkDump.8 \ + man/cryptsetup-fvault2Dump.8 \ + man/cryptsetup-repair.8 \ + man/cryptsetup-benchmark.8 + +CRYPTSETUP_MANLINKS = \ + man/cryptsetup-create.8 \ + man/cryptsetup-plainOpen.8 \ + man/cryptsetup-luksOpen.8 \ + man/cryptsetup-loopaesOpen.8 \ + man/cryptsetup-tcryptOpen.8 \ + man/cryptsetup-bitlkOpen.8 \ + man/cryptsetup-fvault2Open.8 \ + man/cryptsetup-luksErase.8 + +VERITYSETUP_MANPAGES = man/veritysetup.8 +INTEGRITYSETUP_MANPAGES = man/integritysetup.8 +SSHPLUGIN_MANPAGES = man/cryptsetup-ssh.8 + +MANPAGES_ALL = \ + $(CRYPTSETUP_MANPAGES) \ + $(CRYPTSETUP_MANLINKS) \ + $(VERITYSETUP_MANPAGES) \ + $(INTEGRITYSETUP_MANPAGES) \ + $(SSHPLUGIN_MANPAGES) + +MANPAGES = +MANLINKS = + +if CRYPTSETUP +MANPAGES += $(CRYPTSETUP_MANPAGES) +MANLINKS += $(CRYPTSETUP_MANLINKS) +endif +if VERITYSETUP +MANPAGES += $(VERITYSETUP_MANPAGES) +endif +if INTEGRITYSETUP +MANPAGES += $(INTEGRITYSETUP_MANPAGES) +endif +if SSHPLUGIN_TOKEN +MANPAGES += $(SSHPLUGIN_MANPAGES) +endif + +if ENABLE_ASCIIDOC +EXTRA_DIST += $(MANPAGES_ALL) +man8_MANS += $(MANPAGES) $(MANLINKS) + +$(MANPAGES): $(ADOCFILES_COMMON) + +SUFFIXES = .8.adoc .8 +.8.adoc.8: + $(AM_V_GEN) $(ASCIIDOCTOR) -b manpage \ + -a 'release-version=$(VERSION)' \ + --base-dir=$(abs_srcdir) \ + --destination-dir $(abs_builddir)/man $< + +$(MANLINKS): $(MANPAGES) +gen-man: $(man8_MANS) + +gen-man-dist: + @list=`find -name *.adoc -not -path "*/man/common_*" | sed -e 's/\.adoc//g'`; \ + missing=`for p in $$list; do test -f $$p || echo $$p; done`; \ + if test -n "$$missing"; then \ + $(MAKE) $(AM_MAKEFLAGS) $$missing; \ + fi; + +# !ENABLE_ASCIIDOC +else + +if HAVE_MANPAGES +EXTRA_DIST += $(MANPAGES_ALL) +man8_MANS += $(MANPAGES) $(MANLINKS) +endif + +gen-man: +gen-man-dist: +endif + +dist-hook: gen-man-dist diff --git a/man/common_footer.adoc b/man/common_footer.adoc new file mode 100644 index 0000000..21302eb --- /dev/null +++ b/man/common_footer.adoc @@ -0,0 +1,17 @@ + +== REPORTING BUGS + +Report bugs at mailto:cryptsetup@lists.linux.dev[*cryptsetup mailing list*] +or in https://gitlab.com/cryptsetup/cryptsetup/-/issues/new[*Issues project section*]. + +Please attach output of the failed command with --debug option added. + +== SEE ALSO + +https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions[*Cryptsetup FAQ*] + +*cryptsetup*(8), *integritysetup*(8) and *veritysetup*(8) + +== CRYPTSETUP + +Part of https://gitlab.com/cryptsetup/cryptsetup/[*cryptsetup project*]. diff --git a/man/common_options.adoc b/man/common_options.adoc new file mode 100644 index 0000000..56a6e29 --- /dev/null +++ b/man/common_options.adoc @@ -0,0 +1,1195 @@ +== OPTIONS + +ifdef::ACTION_REENCRYPT[] +*--block-size* _value_ *(LUKS1 only)*:: +Use re-encryption block size of _value_ in MiB. ++ +Values can be between 1 and 64 MiB. +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. ++ +Useful if direct-io operations perform better than normal buffered +operations (e.g. in virtual environments). +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--use-fsync (LUKS1 only)*:: +Use fsync call after every written block. This applies for reencryption +log files as well. +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. +endif::[] + +ifdef::ACTION_ISLUKS[] +*--verbose, -v*:: +Print more information on command execution. +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). +endif::[] +ifdef::ACTION_REENCRYPT[] +Specifies required (encryption mode) or expected (other modes) LUKS format. Accepts only _luks1_ or _luks2_. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_TCRYPTDUMP,ACTION_BENCHMARK,ACTION_REENCRYPT[] +*--hash, -h* _<hash-spec>_:: +ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[] +Specifies the passphrase hash. Applies to _plain_ and _loopaes_ device types only. ++ +For _tcrypt_ device type, it restricts checked PBKDF2 variants when looking for header. +endif::[] +ifdef::ACTION_LUKSFORMAT[] +Specifies the hash used in the LUKS key setup scheme and volume key +digest. +endif::[] +ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_TCRYPTDUMP[] +The specified hash is used for PBKDF2 and AF splitter. +endif::[] +ifdef::ACTION_REENCRYPT[] +*LUKS1:* +Specifies the hash used in the LUKS1 key setup scheme and volume key digest. ++ +*NOTE*: if this parameter is not specified, default hash algorithm is always used +for new LUKS1 device header. ++ +*LUKS2:* Ignored unless new keyslot pbkdf algorithm is set to PBKDF2 (see --pbkdf). +endif::[] ++ +ifdef::ACTION_LUKSFORMAT[] +The hash algorithm must provide at least 160 bits of output. +Do not use a non-crypto hash like *xxhash* as this breaks security. +Use _cryptsetup --help_ to show the defaults. +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. ++ +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[] +*LUKS2*: +Set the cipher specification string for data segment only. ++ +*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::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::[] +Ignored on input from file or stdin. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_TCRYPTDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[] +*--key-file, -d* _name_:: +Read the passphrase from file. ++ +If the name given is "-", then the passphrase will be read from stdin. +In this case, reading will not stop at newline characters. ++ +ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY[] +The passphrase supplied via --key-file is always the passphrase for existing +keyslot requested by the command. ++ +If you want to set a new passphrase via key file, you have to use a +positional argument or parameter --new-keyfile. ++ +endif::[] +ifdef::ACTION_OPEN[] +*NOTE:* With _plain_ device type, the passphrase obtained via --key-file option is +passed directly in dm-crypt. Unlike the interactive mode (stdin) +where digest (--hash option) of the passphrase is passed in dm-crypt instead. ++ +endif::[] +ifndef::ACTION_REENCRYPT[] +See section _NOTES ON PASSPHRASE PROCESSING_ in *cryptsetup*(8) for more information. +endif::[] +ifdef::ACTION_REENCRYPT[] +*WARNING:* --key-file option can be used only if there is only one active keyslot, +or alternatively, also if --key-slot option is specified (then all other keyslots +will be disabled in new LUKS device). ++ +If this option is not used, cryptsetup will ask for all active keyslot +passphrases. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[] +*--keyfile-offset* _value_:: +Skip _value_ bytes at the beginning of the key file. +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[] +*--keyfile-size, -l* _value_:: +Read a maximum of _value_ bytes from the key file. The default is to +read the whole file up to the compiled-in maximum that can be queried +with --help. Supplying more data than the compiled-in maximum aborts +the operation. ++ +This option is useful to cut trailing newlines, for example. If +--keyfile-offset is also given, the size count starts after the offset. +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_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[] ++ +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. ++ +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_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. +endif::[] + +ifdef::ACTION_TOKEN[] +*--token-replace*:: +Replace an existing token when adding or importing a token with the +--token-id option. +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. ++ +*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::[] +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[] +*--key-slot, -S <0-N>*:: +ifdef::ACTION_LUKSADDKEY[] +When used together with parameter --new-key-slot this option allows you to specify which +key slot is selected for unlocking volume key. ++ +*NOTE:* This option is ignored if existing volume key gets unlocked +via LUKS2 token (--token-id, --token-type or --token-only parameters) or +when volume key is provided directly via --volume-key-file parameter. ++ +*NOTE:* To maintain backward compatibility, without --new-key-slot parameter, +this option allows you to specify which key slot is selected for the new key. +endif::[] +ifndef::ACTION_OPEN,ACTION_LUKSADDKEY[] +For LUKS operations that add key material, this option allows you to +specify which key slot is selected for the new key. +endif::[] +ifdef::ACTION_OPEN[] +This option selects a specific key-slot to +compare the passphrase against. If the given passphrase would only +match a different key-slot, the operation fails. +endif::[] ++ +ifdef::ACTION_REENCRYPT[] +For reencryption mode it selects specific keyslot (and passphrase) that can be used to unlock new volume key. +If used all other keyslots get removed after reencryption operation is finished. ++ +endif::[] +The maximum number of key slots depends on the LUKS version. LUKS1 can have up +to 8 key slots. LUKS2 can have up to 32 key slots based on key slot area +size and key size, but a valid key slot ID can always be between 0 and +31 for LUKS2. +endif::[] + +ifdef::ACTION_LUKSADDKEY[] +*--new-key-slot <0-N>*:: +This option allows you to specify which key slot is selected for +the new key. ++ +*NOTE:* When used this option affects --key-slot option. ++ +The maximum number of key slots depends on the LUKS version. LUKS1 can have up +to 8 key slots. LUKS2 can have up to 32 key slots based on key slot area +size and key size, but a valid key slot ID can always be between 0 and +31 for LUKS2. +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::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--offset, -o <number of 512 byte sectors>*:: +Start offset in the backend device in 512-byte sectors. +ifdef::ACTION_OPEN[] +This option is only relevant with plain or loopaes device types. +endif::[] +ifdef::ACTION_REENCRYPT[] +This option is only relevant for the encrypt mode. +endif::[] ++ +ifndef::ACTION_OPEN[] +The --offset option sets the data offset (payload) of data +device and must be aligned to 4096-byte sectors (must be multiple of +8). This option cannot be combined with --align-payload option. +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 +keyslot. The PBKDF can be: _pbkdf2_ (for PBKDF2 according to RFC2898), +_argon2i_ for Argon2i or _argon2id_ for Argon2id (see +https://www.cryptolux.org/index.php/Argon2[Argon2] for more info). ++ +For LUKS1, only PBKDF2 is accepted (no need to use this option). The +default PBKDF for LUKS2 is set during compilation time and is available +in _cryptsetup --help_ output. ++ +A PBKDF is used for increasing dictionary and brute-force attack cost +for keyslot passwords. The parameters can be time, memory and parallel +cost. ++ +For PBKDF2, only time cost (number of iterations) applies. For +Argon2i/id, there is also memory cost (memory required during the +process of key derivation) and parallel cost (number of threads that run +in parallel during the key derivation. ++ +Note that increasing memory cost also increases time, so the final +parameter values are measured by a benchmark. The benchmark tries to +find iteration time (_--iter-time_) with required memory cost +_--pbkdf-memory_. If it is not possible, the memory cost is decreased as +well. The parallel cost _--pbkdf-parallel_ is constant and is checked +against available CPU cores. ++ +You can see all PBKDF parameters for particular LUKS2 keyslot with +*cryptsetup-luksDump*(8) command. ++ +*NOTE:* If you do not want to use benchmark and want to specify all +parameters directly, use _--pbkdf-force-iterations_ with +_--pbkdf-memory_ and _--pbkdf-parallel_. This will override the values +without benchmarking. Note it can cause extremely long unlocking time. +Use only in specific cases, for example, if you know that the formatted +device will be used on some small embedded system. ++ +*MINIMAL AND MAXIMAL PBKDF COSTS:* For *PBKDF2*, the minimum iteration +count is 1000 and maximum is 4294967295 (maximum for 32bit unsigned +integer). Memory and parallel costs are unused for PBKDF2. For *Argon2i* +and *Argon2id*, minimum iteration count (CPU cost) is 4 and maximum is +4294967295 (maximum for 32bit unsigned integer). Minimum memory cost is +32 KiB and maximum is 4 GiB. (Limited by addressable memory on some CPU +platforms.) If the memory cost parameter is benchmarked (not specified +by a parameter) it is always in range from 64 MiB to 1 GiB. The parallel +cost minimum is 1 and maximum 4 (if enough CPUs cores are available, +otherwise it is decreased). +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_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] +*--pbkdf-memory <number>*:: +Set the memory cost for PBKDF (for Argon2i/id the number represents +kilobytes). Note that it is maximal value, PBKDF benchmark or +available physical memory can decrease it. This option is not +available for PBKDF2. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] +*--pbkdf-parallel <number>*:: +Set the parallel cost for PBKDF (number of threads, up to 4). Note +that it is maximal value, it is decreased automatically if CPU online +count is lower. 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. +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--progress-frequency* _seconds_:: +ifndef::ACTION_REENCRYPT[] +Print separate line every _seconds_ with wipe progress. +endif::[] +ifdef::ACTION_REENCRYPT[] +Print separate line every _seconds_ with reencryption progress. +endif::[] +endif::[] + +ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +*--progress-json*:: +Prints progress data in JSON format suitable mostly for machine +processing. It prints separate line every half second (or based on +_--progress-frequency_ value). The JSON output looks as follows during +progress (except it's compact single line): ++ +.... +{ + "device":"/dev/sda" // backing device or file + "device_bytes":"8192", // bytes of I/O so far + "device_size":"44040192", // total bytes of I/O to go + "speed":"126877696", // calculated speed in bytes per second (based on progress so far) + "eta_ms":"2520012" // estimated time to finish an operation in milliseconds + "time_ms":"5561235" // total time spent in IO operation in milliseconds +} +.... ++ +Note on numbers in JSON output: Due to JSON parsers limitations all +numbers are represented in a string format due to need of full 64bit +unsigned integers. +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. +endif::[] + +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_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. ++ +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::[] +The _UUID_ must be provided in the standard UUID format, e.g. +12345678-1234-1234-1234-123456789abc. +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::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_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_OPEN[] +*--test-passphrase*:: +Do not activate the device, just verify passphrase. The device mapping name is +not mandatory if this option is used. +endif::[] + +ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP[] +*--header <device or file storing the LUKS header>*:: +ifndef::ACTION_OPEN[] +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. ++ +endif::[] +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[] +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*: +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. ++ +*WARNING:* Never put exported header file in a filesystem on top of device +you are about to decrypt! It would cause a deadlock. +endif::[] +endif::[] + +ifdef::ACTION_LUKSHEADERBACKUP,ACTION_LUKSHEADERRESTORE[] +*--header-backup-file <file>*:: +Specify file with header backup file. +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_CLOSE[] +*--deferred*:: +Defers device removal in _close_ command until the last user closes +it. +endif::[] + +ifdef::ACTION_CLOSE[] +*--cancel-deferred*:: +Removes a previously configured deferred device removal in _close_ +command. +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. ++ +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_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::[] + +ifdef::ACTION_TOKEN[] +*--key-description <text>*:: +Set key description in keyring for use with _token_ command. +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_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_LUKSADDKEY[] +*--token-id*:: +ifndef::ACTION_TOKEN,ACTION_LUKSADDKEY[] +Specify what token to use and allow token PIN prompt to take precedence over interative +keyslot passphrase prompt. If omitted, all available tokens (not protected by PIN) +will be checked before proceeding further with passphrase prompt. +endif::[] +ifdef::ACTION_LUKSADDKEY[] +Specify what token to use when unlocking existing keyslot to get volume key. +endif::[] +ifdef::ACTION_TOKEN[] +Specify token number. If omitted, first unused token id is used when adding or importing +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[] +Do not proceed further with action if token based keyslot unlock failed. Without the +option, action asks for passphrase to proceed further. ++ +It allows LUKS2 tokens protected by PIN to take precedence over interactive keyslot +passphrase prompt. +endif::[] +ifdef::ACTION_LUKSADDKEY[] +Use only LUKS2 tokens to unlock existing volume key. ++ +*NOTE*: To create a new keyslot using passphrase provided by a token use --new-token-id parameter. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[] +*--token-type* _type_:: +ifndef::ACTION_LUKSADDKEY[] +Restrict tokens eligible for operation to specific token _type_. +Mostly useful when no --token-id is specified. ++ +It allows LUKS2 _type_ tokens protected by PIN to take precedence over interactive keyslot +passphrase prompt. +endif::[] +ifdef::ACTION_LUKSADDKEY[] +Specify what token type (all _type_ tokens) to use when unlocking existing keyslot to get volume key. +endif::[] +endif::[] + +ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] +ifndef::ACTION_REENCRYPT[] +*--sector-size* _bytes_:: +endif::[] +ifndef::ACTION_REENCRYPT[] +ifdef::ACTION_OPEN[] +Set encryption sector size for use with _plain_ device type. It must be power of two +and in range 512 - 4096 bytes. 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. +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. +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. +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_OPEN[] +*--refresh*:: +Refreshes an active device with new set of parameters. See +*cryptsetup-refresh*(8) for more details. +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). +endif::[] + +ifdef::ACTION_LUKSFORMAT[] +*--integrity-legacy-padding*:: +Use inefficient legacy padding. ++ +*WARNING*: Do not use this option until you need compatibility with specific +old kernel. +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_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. +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_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_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::[] +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. +endif::[] + +ifdef::ACTION_TCRYPTDUMP,ACTION_OPEN[] +*--veracrypt*:: +This option is ignored as VeraCrypt compatible mode is supported by +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! +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--encrypt, --new, -N*:: +Initialize (and run) device in-place encryption mode. +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--decrypt*:: +Initialize (and run) device decryption mode. +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_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::[] + +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. ++ +Resilience modes can be changed unless _datashift_ mode is used for +operation initialization (encryption with --reduce-device-size option) +endif::[] + +ifdef::ACTION_REENCRYPT[] +*--resilience-hash* _hash_ *(LUKS2 only)*:: +The _hash_ algorithm used with "--resilience checksum" only. The default +hash is sha256. With other resilience modes, the hash parameter is +ignored. +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). ++ +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_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). +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 *#*. ++ +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. +endif::[] + +ifdef::COMMON_OPTIONS[] +*--help, -?*:: +Show help text and default parameters. +endif::[] diff --git a/man/cryptsetup-benchmark.8.adoc b/man/cryptsetup-benchmark.8.adoc new file mode 100644 index 0000000..caaacba --- /dev/null +++ b/man/cryptsetup-benchmark.8.adoc @@ -0,0 +1,41 @@ += cryptsetup-benchmark(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_BENCHMARK: + +== Name + +cryptsetup-benchmark - benchmarks ciphers and KDF + +== SYNOPSIS + +*cryptsetup _benchmark_ [<options>]* + +== DESCRIPTION + +Benchmarks ciphers and KDF (key derivation function). Without +parameters, it tries to measure few common configurations. + +To benchmark other ciphers or modes, you need to specify *--cipher* and +*--key-size* options. + +To benchmark PBKDF you need to specify *--pbkdf* or *--hash* with optional +cost parameters *--iter-time*, *--pbkdf-memory* or *--pbkdf-parallel*. + +*NOTE:* This benchmark uses memory only and is only informative. You +cannot directly predict real storage encryption speed from it. + +For testing block ciphers, this benchmark requires kernel userspace +crypto API to be available (introduced in Linux kernel 2.6.38). If you +are configuring kernel yourself, enable "User-space interface for +symmetric key cipher algorithms" in "Cryptographic API" section +(CRYPTO_USER_API_SKCIPHER .config option). + +*<options>* can be [--cipher, --key-size, --hash, --pbkdf, --iter-time, +--pbkdf-memory, --pbkdf-parallel]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-bitlkDump.8.adoc b/man/cryptsetup-bitlkDump.8.adoc new file mode 100644 index 0000000..6dc273f --- /dev/null +++ b/man/cryptsetup-bitlkDump.8.adoc @@ -0,0 +1,34 @@ += cryptsetup-bitlkDump(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_BITLKDUMP: + +== Name + +cryptsetup-bitlkDump - dump the header information of a BITLK (BitLocker compatible) device + +== SYNOPSIS + +*cryptsetup _bitlkDump_ [<options>] <device>* + +== DESCRIPTION + +Dump the header information of a BITLK (BitLocker compatible) device. + +If the --dump-volume-key option is used, the BITLK device volume key +is dumped instead of header information. You have to provide password +or keyfile to dump volume key. + +Beware that the volume key can be used to decrypt the data stored in +the container without a passphrase. +This means that if the volume key is compromised, the whole device has +to be erased to prevent further access. Use this option carefully. + +*<options>* can be [--dump-volume-key, --volume-key-file, --key-file, +--keyfile-offset, --keyfile-size, --timeout]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-close.8.adoc b/man/cryptsetup-close.8.adoc new file mode 100644 index 0000000..28813d3 --- /dev/null +++ b/man/cryptsetup-close.8.adoc @@ -0,0 +1,30 @@ += cryptsetup-close(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_CLOSE: + +== Name + +cryptsetup-close - removes the existing mapping <name> (and the associated key) + +== SYNOPSIS + +*cryptsetup _close_ [<options>] <name>* + +== DESCRIPTION + +Removes the existing mapping <name> and wipes the key from kernel +memory. + +For backward compatibility, there are *close* command aliases: *remove*, +*plainClose*, *luksClose*, *loopaesClose*, *tcryptClose*, *bitlkClose* +(all behave exactly the same, device type is determined automatically +from the active device). + +*<options>* can be [--deferred, --cancel-deferred, --header, --disable-locks]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-config.8.adoc b/man/cryptsetup-config.8.adoc new file mode 100644 index 0000000..c664242 --- /dev/null +++ b/man/cryptsetup-config.8.adoc @@ -0,0 +1,30 @@ += cryptsetup-config(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_CONFIG: + +== Name + +cryptsetup-config - set permanent configuration options (store to LUKS header) + +== SYNOPSIS + +*cryptsetup _config_ <options> <device>* + +== DESCRIPTION + +Set permanent configuration options (store to LUKS header). The _config_ +command is supported only for LUKS2. + +The permanent options can be _--priority_ to set priority (normal, +prefer, ignore) for keyslot (specified by _--key-slot_) or _--label_ and +_--subsystem_. + +*<options>* can be [--priority, --label, --subsystem, --key-slot, +--header, --disable-locks]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-convert.8.adoc b/man/cryptsetup-convert.8.adoc new file mode 100644 index 0000000..dbb4c23 --- /dev/null +++ b/man/cryptsetup-convert.8.adoc @@ -0,0 +1,37 @@ += cryptsetup-convert(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_CONVERT: + +== Name + +cryptsetup-convert - converts the device between LUKS1 and LUKS2 format + +== SYNOPSIS + +*cryptsetup _convert_ --type <format> [<options>] <device>* + +== DESCRIPTION + +Converts the device between LUKS1 and LUKS2 format (if possible). The +conversion will not be performed if there is an additional LUKS2 feature +or LUKS1 has unsupported header size. + +Conversion (both directions) must be performed on inactive device. There +must not be active dm-crypt mapping established for LUKS header +requested for conversion. + +The *--type* option is mandatory with the following accepted values: _luks1_ or +_luks2_. + +*WARNING:* The _convert_ action can destroy the LUKS header in the case +of a crash during conversion or if a media error occurs. Always create a +header backup before performing this operation! + +*<options>* can be [--header, --type, --disable-locks]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-erase.8.adoc b/man/cryptsetup-erase.8.adoc new file mode 100644 index 0000000..97a13aa --- /dev/null +++ b/man/cryptsetup-erase.8.adoc @@ -0,0 +1,28 @@ += cryptsetup-erase(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_ERASE: + +== Name + +cryptsetup-erase, cryptsetup-luksErase - erase all keyslots + +== SYNOPSIS + +*cryptsetup _erase_ [<options>] <device>* + +*cryptsetup _luksErase_ [<options>] <device>* + +== DESCRIPTION + +Erase all keyslots and make the LUKS container permanently inaccessible. +You do not need to provide any password for this operation. + +*WARNING:* This operation is irreversible. + +*<options>* can be [--header, --disable-locks]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-fvault2Dump.8.adoc b/man/cryptsetup-fvault2Dump.8.adoc new file mode 100644 index 0000000..0831899 --- /dev/null +++ b/man/cryptsetup-fvault2Dump.8.adoc @@ -0,0 +1,34 @@ += cryptsetup-fvault2Dump(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_BITLKDUMP: + +== Name + +cryptsetup-fvault2Dump - dump the header information of a FVAULT2 (FileVault2 compatible) device + +== SYNOPSIS + +*cryptsetup _fvault2Dump_ [<options>] <device>* + +== DESCRIPTION + +Dump the header information of a FVAULT2 (FileVault2 compatible) device. + +If the --dump-volume-key option is used, the FVAULT2 device volume key +is dumped instead of header information. You have to provide password +or keyfile to dump volume key. + +Beware that the volume key can be used to decrypt the data stored in +the container without a passphrase. +This means that if the volume key is compromised, the whole device has +to be erased to prevent further access. Use this option carefully. + +*<options>* can be [--dump-volume-key, --volume-key-file, --key-file, +--keyfile-offset, --keyfile-size, --timeout]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-isLuks.8.adoc b/man/cryptsetup-isLuks.8.adoc new file mode 100644 index 0000000..aac559c --- /dev/null +++ b/man/cryptsetup-isLuks.8.adoc @@ -0,0 +1,29 @@ += cryptsetup-isLuks(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_ISLUKS: + +== Name + +cryptsetup-isLuks - check if a device is a LUKS device + +== SYNOPSIS + +*cryptsetup _isLuks_ [<options>] <device>* + +== DESCRIPTION + +Returns true, if <device> is a LUKS device, false otherwise. + +Use option -v to get human-readable feedback. +'Command successful.' means the device is a LUKS device. + +By specifying --type you may query for specific LUKS version. + +*<options>* can be [--header, --type, --disable-locks]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksAddKey.8.adoc b/man/cryptsetup-luksAddKey.8.adoc new file mode 100644 index 0000000..9686a1d --- /dev/null +++ b/man/cryptsetup-luksAddKey.8.adoc @@ -0,0 +1,71 @@ += cryptsetup-luksAddKey(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSADDKEY: + +== Name + +cryptsetup-luksAddKey - add a new passphrase + +== SYNOPSIS + +*cryptsetup _luksAddKey_ [<options>] <device> [<key file with new key>]* + +== DESCRIPTION + +Adds a keyslot protected by a new passphrase. An existing passphrase +must be supplied interactively, via --key-file or LUKS2 token (plugin). +Alternatively to existing passphrase user may pass directly volume key +(via --volume-key-file). The new passphrase to be added can be specified +interactively, read from the file given as the positional argument (also +via --new-keyfile parameter) or via LUKS2 token. + +*NOTE:* with --unbound option the action creates new unbound LUKS2 +keyslot. The keyslot cannot be used for device activation. If you don't +pass new key via --volume-key-file option, new random key is generated. +Existing passphrase for any active keyslot is not required. + +*NOTE:* some parameters are effective only if used with LUKS2 format +that supports per-keyslot parameters. For LUKS1, PBKDF type and hash +algorithm is always the same for all keyslots. + +*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, +--new-keyfile, --new-keyfile-offset, --new-keyfile-size, --key-slot, +--new-key-slot, --volume-key-file, --force-password, --hash, --header, +--disable-locks, --iter-time, --pbkdf, --pbkdf-force-iterations, +--pbkdf-memory, --pbkdf-parallel, --unbound, --type, --keyslot-cipher, +--keyslot-key-size, --key-size, --timeout, --token-id, --token-type, +--token-only, --new-token-id, --verify-passphrase]. + +include::man/common_options.adoc[] + +== EXAMPLES + +*NOTE*: When not specified otherwise interactive passphrase prompt is always default method. + +Add new keyslot using interactive passphrase prompt for both existing and new passphrase: + +*cryptsetup luksAddKey /dev/device* + +Add new keyslot using LUKS2 tokens to unlock existing keyslot with interactive passphrase prompt for new passphrase: + +*cryptsetup luksAddKey --token-only /dev/device* + +Add new keyslot using LUKS2 systemd-tpm2 tokens to unlock existing keyslot with interactive passphrase prompt for new passphrase (systemd-tpm2 token plugin must be available): + +*cryptsetup luksAddKey --token-type systemd-tpm2 /dev/device* + +Add new keyslot using interactive passphrase prompt for existing keyslot, reading new passphrase from key_file: + +*cryptsetup luksAddKey --new-keyfile key_file /dev/device* or +*cryptsetup luksAddKey /dev/device key_file* + +Add new keyslot using volume stored in volume_key_file and LUKS2 token in slot 5 to get new keyslot passphrase (token in slot 5 must exist +and respective token plugin must be available): + +*cryptsetup luksAddKey --volume-key-file volume_key_file --new-token-id 5 /dev/device* + +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksChangeKey.8.adoc b/man/cryptsetup-luksChangeKey.8.adoc new file mode 100644 index 0000000..7dd5f3b --- /dev/null +++ b/man/cryptsetup-luksChangeKey.8.adoc @@ -0,0 +1,46 @@ += cryptsetup-luksChangeKey(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSCHANGEKEY: + +== Name + +cryptsetup-luksChangeKey - change an existing passphrase + +== SYNOPSIS + +*cryptsetup _luksChangeKey_ [<options>] <device> [<new key file>]* + +== DESCRIPTION + +Changes an existing passphrase. The passphrase to be changed must be +supplied interactively or via --key-file. The new passphrase can be +supplied interactively or in a file given as the positional argument. + +If a key-slot is specified (via --key-slot), the passphrase for that +key-slot must be given and the new passphrase will overwrite the +specified key-slot. If no key-slot is specified and there is still a +free key-slot, then the new passphrase will be put into a free key-slot +before the key-slot containing the old passphrase is purged. If there is +no free key-slot, then the key-slot with the old passphrase is +overwritten directly. + +*WARNING:* If a key-slot is overwritten, a media failure during this +operation can cause the overwrite to fail after the old passphrase has +been wiped and make the LUKS container inaccessible. + +*NOTE:* some parameters are effective only if used with LUKS2 format +that supports per-keyslot parameters. For LUKS1, PBKDF type and hash +algorithm is always the same for all keyslots. + +*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, +--new-keyfile-offset, --iter-time, --pbkdf, --pbkdf-force-iterations, +--pbkdf-memory, --pbkdf-parallel, --new-keyfile-size, --key-slot, +--force-password, --hash, --header, --disable-locks, --type, +--keyslot-cipher, --keyslot-key-size, --timeout, --verify-passphrase]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksConvertKey.8.adoc b/man/cryptsetup-luksConvertKey.8.adoc new file mode 100644 index 0000000..c626542 --- /dev/null +++ b/man/cryptsetup-luksConvertKey.8.adoc @@ -0,0 +1,41 @@ += cryptsetup-luksConvertKey(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSCONVERTKEY: + +== Name + +cryptsetup-luksConvertKey - converts an existing LUKS2 keyslot to new PBKDF parameters + +== SYNOPSIS + +*cryptsetup _luksConvertKey_ [<options>] <device>* + +== DESCRIPTION + +Converts an existing LUKS2 keyslot to new PBKDF parameters. The +passphrase for keyslot to be converted must be supplied interactively or +via --key-file. If no --pbkdf parameters are specified LUKS2 default +PBKDF values will apply. + +If a keyslot is specified (via --key-slot), the passphrase for that +keyslot must be given. If no keyslot is specified and there is still a +free keyslot, then the new parameters will be put into a free keyslot +before the keyslot containing the old parameters is purged. If there is +no free keyslot, then the keyslot with the old parameters is overwritten +directly. + +*WARNING:* If a keyslot is overwritten, a media failure during this +operation can cause the overwrite to fail after the old parameters have +been wiped and make the LUKS container inaccessible. + +*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, +--key-slot, --hash, --header, --disable-locks, --iter-time, --pbkdf, +--pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, +--keyslot-cipher, --keyslot-key-size, --timeout, --verify-passphrase]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksDump.8.adoc b/man/cryptsetup-luksDump.8.adoc new file mode 100644 index 0000000..f9f3910 --- /dev/null +++ b/man/cryptsetup-luksDump.8.adoc @@ -0,0 +1,50 @@ += cryptsetup-luksDump(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSDUMP: + +== Name + +cryptsetup-luksDump - dump the header information of a LUKS device + +== SYNOPSIS + +*cryptsetup _luksDump_ [<options>] <device>* + +== DESCRIPTION + +Dump the header information of a LUKS device. + +If the --dump-volume-key option is used, the LUKS device volume key is +dumped instead of the keyslot info. Together with the --volume-key-file +option, volume key is dumped to a file instead of standard output. +Beware that the volume key cannot be changed without reencryption and +can be used to decrypt the data stored in the LUKS container without a +passphrase and even without the LUKS header. This means that if the +volume key is compromised, the whole device has to be erased or +reencrypted to prevent further access. Use this option carefully. + +To dump the volume key, a passphrase has to be supplied, either +interactively or via --key-file. + +To dump unbound key (LUKS2 format only), --unbound parameter, specific +--key-slot id and proper passphrase has to be supplied, either +interactively or via --key-file. Optional --volume-key-file parameter +enables unbound keyslot dump to a file. + +To dump LUKS2 JSON metadata (without basic header information like UUID) +use --dump-json-metadata option. + +*<options>* can be [--dump-volume-key, --dump-json-metadata, --key-file, +--keyfile-offset, --keyfile-size, --header, --disable-locks, +--volume-key-file, --type, --unbound, --key-slot, --timeout]. + +*WARNING:* If --dump-volume-key is used with --key-file and the argument +to --key-file is '-', no validation question will be asked and no +warning given. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksFormat.8.adoc b/man/cryptsetup-luksFormat.8.adoc new file mode 100644 index 0000000..be241f8 --- /dev/null +++ b/man/cryptsetup-luksFormat.8.adoc @@ -0,0 +1,51 @@ += cryptsetup-luksFormat(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSFORMAT: + +== Name + +cryptsetup-luksFormat - initialize a LUKS partition and set the initial passphrase + +== SYNOPSIS + +*cryptsetup _luksFormat_ [<options>] <device> [<key file>]* + +== DESCRIPTION + +Initializes a LUKS partition and sets the initial passphrase (for +key-slot 0), either via prompting or via <key file>. Note that if the +second argument is present, then the passphrase is taken from the file +given there, without the need to use the --key-file option. Also note +that for both forms of reading the passphrase from a file you can give +'-' as file name, which results in the passphrase being read from stdin +and the safety-question being skipped. + +You cannot call luksFormat on a device or filesystem that is mapped or +in use, e.g., mounted filesystem, used in LVM, active RAID member, etc. The +device or filesystem has to be un-mounted in order to call luksFormat. + +To use specific version of LUKS format, use _--type luks1_ or _type luks2_. + +*<options>* can be [--hash, --cipher, --verify-passphrase, --key-size, +--key-slot, --key-file (takes precedence over optional second argument), +--keyfile-offset, --keyfile-size, --use-random, --use-urandom, --uuid, +--volume-key-file, --iter-time, --header, --pbkdf-force-iterations, +--force-password, --disable-locks, --timeout, --type, --offset, +--align-payload (deprecated)]. + +For LUKS2, additional *<options>* can be [--integrity, +--integrity-no-wipe, --sector-size, --label, --subsystem, --pbkdf, +--pbkdf-memory, --pbkdf-parallel, --disable-locks, --disable-keyring, +--luks2-metadata-size, --luks2-keyslots-size, --keyslot-cipher, +--keyslot-key-size, --integrity-legacy-padding]. + +*WARNING:* Doing a luksFormat on an existing LUKS container will make +all data in the old container permanently irretrievable unless you have a +header backup. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksHeaderBackup.8.adoc b/man/cryptsetup-luksHeaderBackup.8.adoc new file mode 100644 index 0000000..1f57f25 --- /dev/null +++ b/man/cryptsetup-luksHeaderBackup.8.adoc @@ -0,0 +1,35 @@ += cryptsetup-luksHeaderBackup(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSHEADERBACKUP: + +== Name + +cryptsetup-luksHeaderBackup - store a binary backup of the LUKS header and keyslot area + +== SYNOPSIS + +*cryptsetup _luksHeaderBackup_ --header-backup-file <file> [<options>] <device>* + +== DESCRIPTION + +Stores a binary backup of the LUKS header and keyslot area. + +*NOTE:* Using '-' as filename writes the header backup to a file named +'-'. + +*<options>* can be [--header, --header-backup-file, --disable-locks]. + +*WARNING:* This backup file and a passphrase valid at the time of backup +allows decryption of the LUKS data area, even if the passphrase was +later changed or removed from the LUKS device. Also note that with a +header backup you lose the ability to securely wipe the LUKS device by +just overwriting the header and key-slots. You either need to securely +erase all header backups in addition or overwrite the encrypted data +area as well. The second option is less secure, as some sectors can +survive, e.g., due to defect management. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksHeaderRestore.8.adoc b/man/cryptsetup-luksHeaderRestore.8.adoc new file mode 100644 index 0000000..e7fa8aa --- /dev/null +++ b/man/cryptsetup-luksHeaderRestore.8.adoc @@ -0,0 +1,34 @@ += cryptsetup-luksHeaderRestore(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSHEADERRESTORE: + +== Name + +cryptsetup-luksHeaderRestore - restore a binary backup of the LUKS header and keyslot area + +== SYNOPSIS + +*cryptsetup _luksHeaderRestore_ --header-backup-file <file> [<options>] <device>* + +== DESCRIPTION + +Restores a binary backup of the LUKS header and keyslot area from the +specified file. + +*NOTE:* Using '-' as filename reads the header backup from a file named '-'. + +*<options>* can be [--header, --header-backup-file, --disable-locks]. + +*WARNING:* Header and keyslots will be replaced, only the passphrases +from the backup will work afterward. + +This command requires that the volume key size and data offset of the +LUKS header already on the device and of the header backup match. +Alternatively, if there is no LUKS header on the device, the backup will +also be written to it. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksKillSlot.8.adoc b/man/cryptsetup-luksKillSlot.8.adoc new file mode 100644 index 0000000..4575387 --- /dev/null +++ b/man/cryptsetup-luksKillSlot.8.adoc @@ -0,0 +1,40 @@ += cryptsetup-luksKillSlot(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSKILLSLOT: + +== Name + +cryptsetup-luksKillSlot - wipe a key-slot from the LUKS device + +== SYNOPSIS + +*cryptsetup _luksKillSlot_ [<options>] <device> <key slot number>* + +== DESCRIPTION + +Wipe the key-slot number <key slot> from the LUKS device. Except running +in batch-mode (-q) a remaining passphrase must be supplied, either +interactively or via --key-file. This command can remove the last +remaining key-slot, but requires an interactive confirmation when doing +so. Removing the last passphrase makes a LUKS container permanently +inaccessible. + +*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, +--header, --disable-locks, --type, --verify-passphrase, --timeout]. + +*WARNING:* If you read the passphrase from stdin (without further +argument or with '-' as an argument to --key-file), batch-mode (-q) will +be implicitly switched on and no warning will be given when you remove +the last remaining passphrase from a LUKS container. Removing the last +passphrase makes the LUKS container permanently inaccessible. + +*NOTE:* If there is no passphrase provided (on stdin or through +--key-file argument) and batch-mode (-q) is active, the key-slot is +removed without any other warning. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksRemoveKey.8.adoc b/man/cryptsetup-luksRemoveKey.8.adoc new file mode 100644 index 0000000..b414f18 --- /dev/null +++ b/man/cryptsetup-luksRemoveKey.8.adoc @@ -0,0 +1,33 @@ += cryptsetup-luksRemoveKey(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSREMOVEKEY: + +== Name + +cryptsetup-luksRemoveKey - remove the supplied passphrase from the LUKS device + +== SYNOPSIS + +*cryptsetup _luksRemoveKey_ [<options>] <device> [<key file with passphrase to be removed>]* + +== DESCRIPTION + +Removes the supplied passphrase from the LUKS device. The passphrase to +be removed can be specified interactively, as the positional argument or +via --key-file. + +*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, +--header, --disable-locks, --type, --timeout, --verify-passphrase]. + +*WARNING:* If you read the passphrase from stdin (without further +argument or with '-' as an argument to --key-file), batch-mode (-q) will +be implicitly switched on and no warning will be given when you remove +the last remaining passphrase from a LUKS container. Removing the last +passphrase makes the LUKS container permanently inaccessible. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksResume.8.adoc b/man/cryptsetup-luksResume.8.adoc new file mode 100644 index 0000000..9d81cbc --- /dev/null +++ b/man/cryptsetup-luksResume.8.adoc @@ -0,0 +1,29 @@ += cryptsetup-luksResume(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSRESUME: + +== Name + +cryptsetup-luksResume - resume a suspended device and reinstate the key + +== SYNOPSIS + +*cryptsetup _luksResume_ [<options>] <name>* + +== DESCRIPTION + +Resumes a suspended device and reinstates the encryption key. Prompts +interactively for a passphrase if no token is usable (LUKS2 only) or +--key-file is not given. + +*<options>* can be [--key-file, --keyfile-size, --keyfile-offset, +--key-slot, --header, --disable-keyring, --disable-locks, --token-id, +--token-only, --token-type, --disable-external-tokens, --type, --tries, +--timeout, --verify-passphrase]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksSuspend.8.adoc b/man/cryptsetup-luksSuspend.8.adoc new file mode 100644 index 0000000..ed20681 --- /dev/null +++ b/man/cryptsetup-luksSuspend.8.adoc @@ -0,0 +1,33 @@ += cryptsetup-luksSuspend(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSSUSPEND: + +== Name + +cryptsetup-luksSuspend - suspends an active device and wipes the key + +== SYNOPSIS + +*cryptsetup _luksSuspend_ [<options>] <name>* + +== DESCRIPTION + +Suspends an active device (all IO operations will block and accesses to +the device will wait indefinitely) and wipes the encryption key from +kernel memory. Needs kernel 2.6.19 or later. + +After this operation, you have to use _luksResume_ to reinstate the +encryption key and unblock the device or _close_ to remove the mapped +device. + +*<options>* can be [--header, --disable-locks]. + +*WARNING:* Never suspend the device on which the cryptsetup binary +resides. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-luksUUID.8.adoc b/man/cryptsetup-luksUUID.8.adoc new file mode 100644 index 0000000..8ffe9ff --- /dev/null +++ b/man/cryptsetup-luksUUID.8.adoc @@ -0,0 +1,25 @@ += cryptsetup-luksUUID(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_LUKSUUID: + +== Name + +cryptsetup-luksUUID - print or set the UUID of a LUKS device + +== SYNOPSIS + +*cryptsetup _luksUUID_ [<options>] <device>* + +== DESCRIPTION + +Print the UUID of a LUKS device. + +Set new UUID if _--uuid_ option is specified. + +*<options>* can be [--header, --uuid, --type, --disable-locks]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-open.8.adoc b/man/cryptsetup-open.8.adoc new file mode 100644 index 0000000..5e8e7a6 --- /dev/null +++ b/man/cryptsetup-open.8.adoc @@ -0,0 +1,165 @@ += cryptsetup-open(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_OPEN: + +== Name + +cryptsetup-open, cryptsetup-create, cryptsetup-plainOpen, cryptsetup-luksOpen, cryptsetup-loopaesOpen, cryptsetup-tcryptOpen, cryptsetup-bitlkOpen, cryptsetup-fvault2Open - open an encrypted device and create a mapping with a specified name + +== SYNOPSIS + +*cryptsetup _open_ --type <device_type> [<options>] <device> <name>* + +== DESCRIPTION +Opens (creates a mapping with) <name> backed by device <device>. + +Device type can be _plain_, _luks_ (default), _luks1_, _luks2_, +_loopaes_ or _tcrypt_. + +For backward compatibility there are *open* command aliases: + +*create* (argument-order <name> <device>): open --type plain + +*plainOpen*: open --type plain + +*luksOpen*: open --type luks + +*loopaesOpen*: open --type loopaes + +*tcryptOpen*: open --type tcrypt + +*bitlkOpen*: open --type bitlk + +*<options>* are type specific and are described below for individual +device types. For *create*, the order of the <name> and <device> options +is inverted for historical reasons, all other aliases use the standard +*<device> <name>* order. + +=== PLAIN +*open --type plain <device> <name>* + +plainOpen <device> <name> (*old syntax*) + +create <name> <device> (*OBSOLETE syntax*) + +Opens (creates a mapping with) <name> backed by device <device>. + +*<options>* can be [--hash, --cipher, --verify-passphrase, --sector-size, +--key-file, --keyfile-size, --keyfile-offset, --key-size, --offset, +--skip, --device-size, --size, --readonly, --shared, --allow-discards, +--refresh, --timeout, --verify-passphrase, --iv-large-sectors]. + +Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the raw +encrypted device /dev/sda10 to the mapped (decrypted) device +/dev/mapper/e1, which can then be mounted, fsck-ed or have a filesystem +created on it. + +=== LUKS +*open <device> <name>* + +open --type <luks1|luks2> <device> <name> (*explicit version request*) + +luksOpen <device> <name> (*old syntax*) + +Opens the LUKS device <device> and sets up a mapping <name> after +successful verification of the supplied passphrase. + +First, the passphrase is searched in LUKS2 tokens unprotected by PIN. +If such token does not exist (or fails to unlock keyslot) and +also the passphrase is not supplied via --key-file, the command +prompts for passphrase interactively. + +If there is valid LUKS2 token but it requires PIN to unlock assigned keyslot, +it is not used unless one of following options is added: --token-only, +--token-type where type matches desired PIN protected token or --token-id with id +matching PIN protected token. + +*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, +--readonly, --test-passphrase, --allow-discards, --header, --key-slot, +--volume-key-file, --token-id, --token-only, --token-type, +--disable-external-tokens, --disable-keyring, --disable-locks, --type, +--refresh, --serialize-memory-hard-pbkdf, --unbound, --tries, --timeout, +--verify-passphrase, --persistent]. + +=== loopAES +*open --type loopaes <device> <name> --key-file <keyfile>* + +loopaesOpen <device> <name> --key-file <keyfile> (*old syntax*) + +Opens the loop-AES <device> and sets up a mapping <name>. + +If the key file is encrypted with GnuPG, then you have to use +--key-file=- and decrypt it before use, e.g., like this: + +gpg --decrypt <keyfile> | cryptsetup loopaesOpen --key-file=- <device> +<name> + +*WARNING:* The loop-AES extension cannot use the direct input of the key +file on the real terminal because the keys are separated by end-of-line and +only part of the multi-key file would be read. + +If you need it in script, just use the pipe redirection: + +echo $keyfile | cryptsetup loopaesOpen --key-file=- <device> <name> + +Use *--keyfile-size* to specify the proper key length if needed. + +Use *--offset* to specify device offset. Note that the units need to be +specified in number of 512 byte sectors. + +Use *--skip* to specify the IV offset. If the original device used an +offset and but did not use it in IV sector calculations, you have to +explicitly use *--skip 0* in addition to the offset parameter. + +Use *--hash* to override the default hash function for passphrase +hashing (otherwise it is detected according to key size). + +*<options>* can be [--cipher, --key-file, --keyfile-size, --keyfile-offset, +--key-size, --offset, --skip, --hash, --readonly, --allow-discards, --refresh]. + +=== TrueCrypt and VeraCrypt +*open --type tcrypt <device> <name>* + +tcryptOpen <device> <name> (*old syntax*) + +Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) <device> and sets +up a mapping <name>. + +*<options>* can be [--key-file, --tcrypt-hidden, --tcrypt-system, +--tcrypt-backup, --readonly, --test-passphrase, --allow-discards, +--veracrypt (ignored), --disable-veracrypt, --veracrypt-pim, +--veracrypt-query-pim, --header, +--cipher, --hash, --tries, --timeout, --verify-passphrase]. + +The keyfile parameter allows a combination of file content with the +passphrase and can be repeated. Note that using keyfiles is compatible +with TCRYPT and is different from LUKS keyfile logic. + +If *--cipher* or *--hash* options are used, only cipher chains or PBKDF2 +variants with the specified hash algorithms are checked. This could +speed up unlocking the device (but also it reveals some information +about the container). + +If you use *--header* in combination with hidden or system options, the +header file must contain specific headers on the same positions as the +original encrypted container. + +*WARNING:* Option *--allow-discards* cannot be combined with option +*--tcrypt-hidden*. For normal mapping, it can cause the *destruction of +hidden volume* (hidden volume appears as unused space for outer volume +so this space can be discarded). + +=== BitLocker +*open --type bitlk <device> <name>* + +bitlkOpen <device> <name> (*old syntax*) + +Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping +<name>. + +*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, +--readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, +--timeout, --verify-passphrase]. + +=== FileVault2 +*open --type fvault2 <device> <name>* + +fvault2Open <device> <name> (*old syntax*) + +Opens the FVAULT2 (a FileVault2 compatible) <device> and sets up a mapping +<name>. + +*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, +--readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, +--timeout, --verify-passphrase]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-reencrypt.8.adoc b/man/cryptsetup-reencrypt.8.adoc new file mode 100644 index 0000000..154a469 --- /dev/null +++ b/man/cryptsetup-reencrypt.8.adoc @@ -0,0 +1,175 @@ += cryptsetup-reencrypt(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_REENCRYPT: + +== Name + +cryptsetup-reencrypt - reencrypt LUKS encrypted volumes in-place + +== SYNOPSIS + +*cryptsetup _reencrypt_ [<options>] <device> or --active-name <name> [<new_name>]* + +== DESCRIPTION + +Run LUKS device reencryption. + +There are 3 basic modes of operation: + +* device reencryption (_reencrypt_) +* device encryption (_reencrypt_ --encrypt/--new/-N) +* device decryption (_reencrypt_ --decrypt) + +<device> or --active-name <name> (LUKS2 only) is mandatory parameter. + +Cryptsetup _reencrypt_ action can be used to change reencryption parameters +which otherwise require full on-disk data change (re-encryption). The +_reencrypt_ action reencrypts data on LUKS device in-place. + +You can regenerate *volume key* (the real key used in on-disk encryption +unclocked by passphrase), *cipher*, *cipher mode* or *encryption sector size* +(LUKS2 only). + +Reencryption process may be safely interrupted by a user via SIGINT +signal (ctrl+c). Same applies to SIGTERM signal (i.e. issued by systemd +during system shutdown). + +For in-place encryption mode, the _reencrypt_ action additionally takes all +options available for _luksFormat_ action for respective LUKS version (see +cryptsetup-luksFormat man page for more details). See *cryptsetup-luksFormat*(8). + +*NOTE* that for encrypt and decrypt mode, the whole device must be +treated as unencrypted -- there are no quarantees of confidentiality as +part of the device contains plaintext. + +*ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS ACTION ON LUKS DEVICE.* + +*<options>* can be [--batch-mode, +--block-size, +--cipher, +--debug, +--debug-json, +--decrypt, +--device-size, +--disable-locks, +--encrypt, +--force-offline-reencrypt, +--hash, +--header, +--hotzone-size, +--iter-time, +--init-only, +--keep-key, +--key-file, +--key-size, +--key-slot, +--keyfile-offset, +--keyfile-size, +--tries, +--timeout, +--pbkdf, +--pbkdf-force-iterations, +--pbkdf-memory, +--pbkdf-parallel, +--progress-frequency, +--progress-json, +--reduce-device-size, +--resilience, +--resilience-hash, +--resume-only, +--sector-size, +--use-directio, +--use-random, +--use-urandom, +--use-fsync, +--uuid, +--verbose, +--volume-key-file, +--write-log]. + +== LUKS2 REENCRYPTION + +With <device> parameter cryptsetup looks up active <device> dm mapping. +If no active mapping is detected, it starts offline LUKS2 reencryption +otherwise online reencryption takes place. + +To resume already initialized or interrupted reencryption, just run the +cryptsetup _reencrypt_ command again to continue the reencryption +operation. Reencryption may be resumed with different --resilience or +--hotzone-size unless implicit datashift resilience mode is used: either +encrypt mode with --reduce-device-size option or decrypt mode with +original LUKS2 header exported in --header file. + +If the reencryption process was interrupted abruptly (reencryption +process crash, system crash, poweroff) it may require recovery. The +recovery is currently run automatically on next activation (action +_open_) when needed or explicitly by user (action _repair_). + +Optional parameter <new_name> takes effect only with encrypt option +and it activates device <new_name> immediately after encryption +initialization gets finished. That's useful when device needs to be +ready as soon as possible and mounted (used) before full data area +encryption is completed. + +== LUKS1 REENCRYPTION + +Current working directory must be writable and temporary files created during +reencryption must be present. During reencryption process the LUKS1 device is +marked unavailable and must be offline (no dm-crypt mapping or mounted +filesystem). + +*WARNING*: The LUKS1 reencryption code is not resistant to hardware +or kernel failures during reencryption (you can lose your data in this case). + +include::man/common_options.adoc[] + +== EXAMPLES + +*NOTE*: You may drop *--type luks2* option as long as LUKS2 format is +default. + +=== LUKS2 ENCRYPTION EXAMPLES + +Encrypt LUKS2 device (in-place). Make sure last 32 MiB on _/dev/plaintext_ +is unused (e.g.: does not contain filesystem data): + +*cryptsetup reencrypt --encrypt --type luks2 --reduce-device-size 32m /dev/plaintext_device* + +Encrypt LUKS2 device (in-place) with detached header put in a file: + +*cryptsetup reencrypt --encrypt --type luks2 --header my_luks2_header /dev/plaintext_device* + +Initialize LUKS2 in-place encryption operation only and activate the device (not yet encrypted): + +*cryptsetup reencrypt --encrypt --type luks2 --init-only --reduce-device-size 32m /dev/plaintext_device my_future_luks_device* + +Resume online encryption on device initialized in example above: + +*cryptsetup reencrypt --resume-only /dev/plaintext_device* or +*cryptsetup reencrypt --active-name my_future_luks_device* + +=== LUKS2 REENCRYPTION EXAMPLES + +Reencrypt LUKS2 device (refresh volume key only): + +*cryptsetup reencrypt /dev/encrypted_device* + +=== LUKS2 DECRYPTION EXAMPLES + +Decrypt LUKS2 device with header put in head of data device (header file does not exist): + +*cryptsetup reencrypt --decrypt --header /export/header/to/file /dev/encrypted_device* + +Decrypt LUKS2 device with detached header (header file exists): + +*cryptsetup reencrypt --decrypt --header detached-luks2-header /dev/encrypted_device* + +Resume interrupted LUKS2 decryption: + +*cryptsetup reencrypt --resume-only --header luks2-hdr-file /dev/encrypted_device* + +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-refresh.8.adoc b/man/cryptsetup-refresh.8.adoc new file mode 100644 index 0000000..b79a80a --- /dev/null +++ b/man/cryptsetup-refresh.8.adoc @@ -0,0 +1,53 @@ += cryptsetup-refresh(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_REFRESH: + +== Name + +cryptsetup-refresh - refresh parameters of an active mapping + +== SYNOPSIS + +*cryptsetup _refresh_ [<options>] <name>* + +== DESCRIPTION + +Refreshes parameters of active mapping <name>. + +Updates parameters of active device <name> without the need to deactivate +the device (and umount filesystem). Currently, it supports parameters +refresh on following devices: LUKS1, LUKS2 (including authenticated +encryption), plain crypt and loop-AES. + +Mandatory parameters are identical to those of an open action for +the respective device type. + +You may change following parameters on all devices +--perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, +--perf-no_read_workqueue, --perf-no_write_workqueue and +--allow-discards. + +Refreshing the device without any optional parameter will refresh the device +with default setting (respective to device type). + +*LUKS2 only:* + +The --integrity-no-journal parameter affects only LUKS2 devices with +the underlying dm-integrity device. + +Adding option --persistent stores any combination of device parameters +above in LUKS2 metadata (only after successful refresh operation). + +The --disable-keyring parameter refreshes a device with volume key passed in +dm-crypt driver. + +*<options>* can be [--allow-discards, --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, +--perf-no_read_workqueue, --perf-no_write_workqueue, --header, --disable-keyring, +--disable-locks, --persistent, --integrity-no-journal]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-repair.8.adoc b/man/cryptsetup-repair.8.adoc new file mode 100644 index 0000000..22ad9cb --- /dev/null +++ b/man/cryptsetup-repair.8.adoc @@ -0,0 +1,43 @@ += cryptsetup-repair(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_REPAIR: + +== Name + +cryptsetup-repair - repair the device metadata + +== SYNOPSIS + +*cryptsetup _repair_ [<options>] <device>* + +== DESCRIPTION + +Tries to repair the device metadata if possible. Currently supported +only for LUKS device type. + +This command is useful to fix some known benign LUKS metadata header +corruptions. Only basic corruptions of unused keyslot are fixable. This +command will only change the LUKS header, not any key-slot data. You may +enforce LUKS version by adding --type option. + +It also repairs (upgrades) LUKS2 reencryption metadata by adding +a metadata digest that protects it against malicious changes. + +If LUKS2 reencryption was interrupted in the middle of writing +reencryption segment the repair command can be used to perform +reencryption recovery so that reencryption can continue later. +Repairing reencryption requires verification of reencryption +keyslot so passphrase or keyfile is needed. + +*<options>* can be [--timeout, --verify-passphrase, --disable-locks, +--type, --header, --key-file, --keyfile-size, --keyfile-offset, --key-slot]. + +*WARNING:* Always create a binary backup of the original header before +calling this command. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-resize.8.adoc b/man/cryptsetup-resize.8.adoc new file mode 100644 index 0000000..4cff482 --- /dev/null +++ b/man/cryptsetup-resize.8.adoc @@ -0,0 +1,42 @@ += cryptsetup-resize(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_RESIZE: + +== Name + +cryptsetup-resize - resize an active mapping + +== SYNOPSIS + +*cryptsetup _resize_ [<options>] <name>* + +== DESCRIPTION + +Resizes an active mapping <name>. + +If --size (in 512-bytes sectors) or --device-size are not specified, the +size is computed from the underlying device. For LUKS it is the size of +the underlying device without the area reserved for LUKS header (see +data payload offset in *luksDump* command). For plain crypt device, the +whole device size is used. + +Note that this does not change the raw device geometry, it just changes +how many sectors of the raw device are represented in the mapped device. + +If cryptsetup detected volume key for active device loaded in kernel +keyring service, resize action would first try to retrieve the key using +a token. Only if it failed, it'd ask for a passphrase to unlock a +keyslot (LUKS) or to derive a volume key again (plain mode). The kernel +keyring is used by default for LUKS2 devices. + +*<options>* can be [--size, --device-size, --token-id, --token-only, +--token-type, --key-slot, --key-file, --keyfile-size, --keyfile-offset, +--timeout, --disable-external-tokens, --disable-locks, --disable-keyring, +--verify-passphrase, --timeout]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-ssh.8.adoc b/man/cryptsetup-ssh.8.adoc new file mode 100644 index 0000000..f71f856 --- /dev/null +++ b/man/cryptsetup-ssh.8.adoc @@ -0,0 +1,80 @@ += cryptsetup-ssh(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup-ssh {release-version} +:man-linkstyle: pass:[blue R < >] + +== NAME + +cryptsetup-ssh - manage LUKS2 SSH token + +== SYNOPSIS + +*cryptsetup-ssh <action> [<options>] <action args>* + +== DESCRIPTION + +Experimental cryptsetup plugin for unlocking LUKS2 devices with token +connected to an SSH server. + +This plugin currently allows only adding a token to an existing key +slot. See *cryptsetup(8)* for instructions on how to remove, import or +export the token. + +=== Add operation + +*add <options> <device>* + +Adds the SSH token to *<device>*. + +The specified SSH server must contain a key file on the specified path with +a passphrase for an existing key slot on the device. Provided +credentials will be used by cryptsetup to get the password when opening +the device using the token. + +Options --ssh-server, --ssh-user, --ssh-keypath and --ssh-path are +required for this operation. + +== OPTIONS + +**--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. + +**--ssh-keypath**=_STRING_:: +Path to the SSH key for connecting to the remote server. + +**--ssh-path**=_STRING_:: +Path to the key file on the remote server. + +**--ssh-server**=_STRING_:: +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 + +== NOTES + +The information provided when adding the token (SSH server address, user +and paths) will be stored in the LUKS2 header in plaintext. + +== AUTHORS + +The cryptsetup-ssh tool is written by Vojtech Trefny. + +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-status.8.adoc b/man/cryptsetup-status.8.adoc new file mode 100644 index 0000000..1152f55 --- /dev/null +++ b/man/cryptsetup-status.8.adoc @@ -0,0 +1,24 @@ += cryptsetup-status(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_STATUS: + +== Name + +cryptsetup-status - report the status for a mapping + +== SYNOPSIS + +*cryptsetup _status_ [<options>] <name>* + +== DESCRIPTION + +Reports the status for the mapping <name>. + +*<options>* can be [--header, --disable-locks]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-tcryptDump.8.adoc b/man/cryptsetup-tcryptDump.8.adoc new file mode 100644 index 0000000..51d5041 --- /dev/null +++ b/man/cryptsetup-tcryptDump.8.adoc @@ -0,0 +1,37 @@ += cryptsetup-tcryptDump(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_TCRYPTDUMP: + +== Name + +cryptsetup-tcryptDump - dump the header information of a TCRYPT (TrueCrypt or VeraCrypt compatible) device + +== SYNOPSIS + +*cryptsetup _tcryptDump_ [<options>] <device>* + +== DESCRIPTION + +Dump the header information of a TCRYPT (TrueCrypt or VeraCrypt compatible) device. + +If the --dump-volume-key option is used, the TCRYPT device volume key is +dumped instead of TCRYPT header info. Beware that the volume key (or +concatenated volume keys if cipher chain is used) can be used to decrypt +the data stored in the TCRYPT container without a passphrase. This means +that if the volume key is compromised, the whole device has to be erased +to prevent further access. Use this option carefully. + +*<options>* can be [--dump-volume-key, --key-file, --tcrypt-hidden, +--tcrypt-system, --tcrypt-backup, --veracrypt (ignored), --disable-veracrypt, +--veracrypt-pim, --veracrypt-query-pim, --cipher, --hash, --header, +--verify-passphrase, --timeout]. + +The keyfile parameter allows a combination of file content with the +passphrase and can be repeated. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup-token.8.adoc b/man/cryptsetup-token.8.adoc new file mode 100644 index 0000000..7a3a069 --- /dev/null +++ b/man/cryptsetup-token.8.adoc @@ -0,0 +1,55 @@ += cryptsetup-token(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] +:COMMON_OPTIONS: +:ACTION_TOKEN: + +== Name + +cryptsetup-token - manage LUKS2 tokens + +== SYNOPSIS + +*cryptsetup _token_ <add|remove|import|export|unassign> [<options>] <device>* + +== DESCRIPTION + +Action _add_ creates a new keyring token to enable auto-activation of the +device. For the auto-activation, the passphrase must be stored in +keyring with the specified description. Usually, the passphrase should +be stored in _user_ or _user-session_ keyring. The _token_ command is +supported only for LUKS2. + +For adding new keyring token, option --key-description is mandatory. +Also, new token is assigned to key slot specified with --key-slot option +or to all active key slots in the case --key-slot option is omitted. + +To remove existing token, specify the token ID which should be removed +with --token-id option. + +*WARNING:* The action _token remove_ removes any token type, not just +_keyring_ type from token slot specified by --token-id option. + +Action _import_ can store arbitrary valid token json in LUKS2 header. It +may be passed via standard input or via file passed in --json-file +option. If you specify --key-slot then successfully imported token is +also assigned to the key slot. + +Action _export_ writes requested token JSON to a file passed with +--json-file or to standard output. + +Action _unassign_ removes token binding to specified keyslot. Both token +and keyslot must be specified by --token-id and --key-slot parameters. + +If --token-id is used with action _add_ or action _import_ and a token +with that ID already exists, option --token-replace can be used to +replace the existing token. + +*<options>* can be [--header, --token-id, --key-slot, --key-description, +--disable-external-tokens, --disable-locks, --disable-keyring, +--json-file, --token-replace, --unbound]. + +include::man/common_options.adoc[] +include::man/common_footer.adoc[] diff --git a/man/cryptsetup.8.adoc b/man/cryptsetup.8.adoc new file mode 100644 index 0000000..ddd3a12 --- /dev/null +++ b/man/cryptsetup.8.adoc @@ -0,0 +1,729 @@ += cryptsetup(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: cryptsetup {release-version} +:man-linkstyle: pass:[blue R < >] + +== Name + +cryptsetup - manage plain dm-crypt, LUKS, and other encrypted volumes + +== SYNOPSIS + +*cryptsetup <action> [<options>] <action args>* + +== DESCRIPTION + +cryptsetup is used to conveniently setup dm-crypt managed device-mapper +mappings. These include plain dm-crypt volumes and LUKS volumes. The +difference is that LUKS uses a metadata header and can hence offer more +features than plain dm-crypt. On the other hand, the header is visible +and vulnerable to damage. + +In addition, cryptsetup provides limited support for the use of loop-AES +volumes, TrueCrypt, VeraCrypt, BitLocker and FileVault2 compatible volumes. + +For more information about specific cryptsetup action see +*cryptsetup-<action>*(8), where *<action>* is the name of the +cryptsetup action. + +== BASIC ACTIONS + +The following are valid actions for all supported device types. + +=== OPEN +*open <device> <name> --type <device_type>* + +Opens (creates a mapping with) <name> backed by device <device>. + +See *cryptsetup-open*(8). + +=== CLOSE +*close <name>* + +Removes the existing mapping <name> and wipes the key from kernel memory. + +See *cryptsetup-close*(8). + +=== STATUS +*status <name>* + +Reports the status for the mapping <name>. + +See *cryptsetup-status*(8). + +=== RESIZE +*resize <name>* + +Resizes an active mapping <name>. + +See *cryptsetup-resize*(8). + +=== REFRESH +*refresh <name>* + +Refreshes parameters of active mapping <name>. + +See *cryptsetup-refresh*(8). + +=== REENCRYPT +*reencrypt <device> or --active-name <name> [<new_name>]* + +Run LUKS device reencryption. + +See *cryptsetup-reencrypt*(8). + +== PLAIN MODE + +Plain dm-crypt encrypts the device sector-by-sector with a single, +non-salted hash of the passphrase. No checks are performed, no metadata +is used. There is no formatting operation. When the raw device is mapped +(opened), the usual device operations can be used on the mapped device, +including filesystem creation. Mapped devices usually reside in +/dev/mapper/<name>. + +The following are valid plain device type actions: + +=== OPEN +*open --type plain <device> <name>* + +create <name> <device> (*OBSOLETE syntax*) + +Opens (creates a mapping with) <name> backed by device <device>. + +See *cryptsetup-open*(8). + +== LUKS EXTENSION + +LUKS, the Linux Unified Key Setup, is a standard for disk encryption. It +adds a standardized header at the start of the device, a key-slot area +directly behind the header and the bulk data area behind that. The whole +set is called a 'LUKS container'. The device that a LUKS container +resides on is called a 'LUKS device'. For most purposes, both terms can +be used interchangeably. But note that when the LUKS header is at a +nonzero offset in a device, then the device is not a LUKS device +anymore, but has a LUKS container stored in it at an offset. + +LUKS can manage multiple passphrases that can be individually revoked or +changed and that can be securely scrubbed from persistent media due to +the use of anti-forensic stripes. Passphrases are protected against +brute-force and dictionary attacks by Password-Based Key Derivation +Function (PBKDF). + +LUKS2 is a new version of header format that allows additional +extensions like different PBKDF algorithm or authenticated encryption. +You can format device with LUKS2 header if you specify *--type luks2* in +*luksFormat* command. For activation, the format is already recognized +automatically. + +Each passphrase, also called a *key* in this document, is associated +with one of 8 key-slots. Key operations that do not specify a slot +affect the first slot that matches the supplied passphrase or the first +empty slot if a new passphrase is added. + +The *<device>* parameter can also be specified by a LUKS UUID in the +format UUID=<uuid>. Translation to real device name uses symlinks in +/dev/disk/by-uuid directory. + +To specify a detached header, the *--header* parameter can be used in +all LUKS commands and always takes precedence over the positional +*<device>* parameter. + +The following are valid LUKS actions: + +=== FORMAT +*luksFormat <device> [<key file>]* + +Initializes a LUKS partition and sets the initial passphrase (for key-slot 0). + +See *cryptsetup-luksFormat*(8). + +=== OPEN +*open --type luks <device> <name>* + +luksOpen <device> <name> (*old syntax*) + +Opens the LUKS device <device> and sets up a mapping <name> after +successful verification of the supplied passphrase. + +See *cryptsetup-open*(8). + +=== SUSPEND +*luksSuspend <name>* + +Suspends an active device (all IO operations will block and accesses to +the device will wait indefinitely) and wipes the encryption key from +kernel memory. + +See *cryptsetup-luksSuspend*(8). + +=== RESUME +*luksResume <name>* + +Resumes a suspended device and reinstates the encryption key. + +See *cryptsetup-luksResume*(8). + +=== ADD KEY +*luksAddKey <device> [<key file with new key>]* + +Adds a new passphrase using an existing passphrase. + +See *cryptsetup-luksAddKey*(8). + +=== REMOVE KEY +*luksRemoveKey <device> [<key file with passphrase to be removed>]* + +Removes the supplied passphrase from the LUKS device. + +See *cryptsetup-luksRemoveKey*(8). + +=== CHANGE KEY +*luksChangeKey <device> [<new key file>]* + +Changes an existing passphrase. + +See *cryptsetup-luksChangeKey*(8). + +=== CONVERT KEY +*luksConvertKey <device>* + +Converts an existing LUKS2 keyslot to new PBKDF parameters. + +See *cryptsetup-luksConvertKey*(8). + +=== KILL SLOT +*luksKillSlot <device> <key slot number>* + +Wipe the key-slot number <key slot> from the LUKS device. + +See *cryptsetup-luksKillSlot*(8). + +=== ERASE +*erase <device>* + +luksErase <device> (*old syntax*) + +Erase all keyslots and make the LUKS container permanently inaccessible. + +See *cryptsetup-erase*(8). + +=== UUID +*luksUUID <device>* + +Print or set the UUID of a LUKS device. + +See *cryptsetup-luksUUID*(8). + +=== IS LUKS +*isLuks <device>* + +Returns true, if <device> is a LUKS device, false otherwise. + +See *cryptsetup-isLuks*(8). + +=== DUMP +*luksDump <device>* + +Dump the header information of a LUKS device. + +See *cryptsetup-luksDump*(8). + +=== HEADER BACKUP +*luksHeaderBackup <device> --header-backup-file <file>* + +Stores a binary backup of the LUKS header and keyslot area. + +See *cryptsetup-luksHeaderBackup*(8). + +=== HEADER RESTORE +*luksHeaderRestore <device> --header-backup-file <file>* + +Restores a binary backup of the LUKS header and keyslot area from the +specified file. + +See *cryptsetup-luksHeaderRestore*(8). + +=== TOKEN +*token <add|remove|import|export> <device>* + +Manipulate token objects used for obtaining passphrases. + +See *cryptsetup-token*(8). + +=== CONVERT +*convert <device> --type <format>* + +Converts the device between LUKS1 and LUKS2 format (if possible). + +See *cryptsetup-convert*(8). + +=== CONFIG +*config <device>* + +Set permanent configuration options (store to LUKS header). + +See *cryptsetup-config*(8). + +== loop-AES EXTENSION + +cryptsetup supports mapping loop-AES encrypted partition using a +compatibility mode. + +=== OPEN +*open --type loopaes <device> <name> --key-file <keyfile>* + +loopaesOpen <device> <name> --key-file <keyfile> (*old syntax*) + +Opens the loop-AES <device> and sets up a mapping <name>. + +See *cryptsetup-open*(8). + +See also section 7 of the FAQ and http://loop-aes.sourceforge.net[loop-AES] +for more information regarding loop-AES. + +== TCRYPT (TrueCrypt and VeraCrypt compatible) EXTENSION + +cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt encrypted +partition using a native Linux kernel API. Header formatting and TCRYPT +header change is not supported, cryptsetup never changes TCRYPT header +on-device. + +TCRYPT extension requires kernel userspace crypto API to be available +(introduced in Linux kernel 2.6.38). If you are configuring kernel +yourself, enable "User-space interface for symmetric key cipher +algorithms" in "Cryptographic API" section +(CRYPTO_USER_API_SKCIPHER .config option). + +Because TCRYPT header is encrypted, you have to always provide valid +passphrase and keyfiles. + +Cryptsetup should recognize all header variants, except legacy cipher +chains using LRW encryption mode with 64 bits encryption block (namely +Blowfish in LRW mode is not recognized, this is limitation of kernel +crypto API). + +VeraCrypt is extension of TrueCrypt header with increased iteration +count so unlocking can take quite a lot of time. + +To open a VeraCrypt device with a custom Personal Iteration Multiplier +(PIM) value, use either the *--veracrypt-pim=<PIM>* option to directly +specify the PIM on the command- line or use *--veracrypt-query-pim* to +be prompted for the PIM. + +The PIM value affects the number of iterations applied during key +derivation. Please refer to +https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html[PIM] +for more detailed information. + +If you need to disable VeraCrypt device support, use +*--disable-veracrypt* option. + +*NOTE:* Activation with *tcryptOpen* is supported only for cipher chains +using LRW or XTS encryption modes. + +The *tcryptDump* command should work for all recognized TCRYPT devices +and doesn't require superuser privilege. + +To map system device (device with boot loader where the whole encrypted +system resides) use *--tcrypt-system* option. You can use partition +device as the parameter (parameter must be real partition device, not an +image in a file), then only this partition is mapped. + +If you have the whole TCRYPT device as a file image and you want to map +multiple partition encrypted with system encryption, please create +loopback mapping with partitions first (*losetup -P*, see *losetup(8)* +man page for more info), and use loop partition as the device parameter. + +If you use the whole base device as a parameter, one device for the +whole system encryption is mapped. This mode is available only for +backward compatibility with older cryptsetup versions which mapped +TCRYPT system encryption using the whole device. + +To use hidden header (and map hidden device, if available), use +*--tcrypt-hidden* option. + +To explicitly use backup (secondary) header, use *--tcrypt-backup* +option. + +*NOTE:* There is no protection for a hidden volume if the outer volume +is mounted. The reason is that if there were any protection, it would +require some metadata describing what to protect in the outer volume and +the hidden volume would become detectable. + +=== OPEN +*open --type tcrypt <device> <name>* + +tcryptOpen_ <device> <name> (*old syntax*) + +Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a mapping +<name>. + +See *cryptsetup-open*(8). + +=== DUMP +*tcryptDump <device>* + +Dump the header information of a TCRYPT device. + +See *cryptsetup-tcryptDump*(8). + +See also https://en.wikipedia.org/wiki/TrueCrypt[*TrueCrypt*] and +https://en.wikipedia.org/wiki/VeraCrypt[*VeraCrypt*] pages for more information. + +Please note that cryptsetup does not use TrueCrypt or VeraCrypt code, please +report all problems related to this compatibility extension to the cryptsetup +project. + +== BITLK (Windows BitLocker compatible) EXTENSION + +cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted +partition using a native Linux kernel API. Header formatting and BITLK +header changes are not supported, cryptsetup never changes BITLK header +on-device. + +BITLK extension requires kernel userspace crypto API to be available +(for details see TCRYPT section). + +Cryptsetup should recognize all BITLK header variants, except legacy +header used in Windows Vista systems and partially decrypted BitLocker +devices. Activation of legacy devices encrypted in CBC mode requires at +least Linux kernel version 5.3 and for devices using Elephant diffuser +kernel 5.6. + +The *bitlkDump* command should work for all recognized BITLK devices and +doesn't require superuser privilege. + +For unlocking with the *open* a password or a recovery passphrase or a +startup key must be provided. + +Additionally unlocking using volume key is supported. You must provide +BitLocker Full Volume Encryption Key (FVEK) using the --volume-key-file +option. The key must be decrypted and without the header (only +128/256/512 bits of key data depending on used cipher and mode). + +Other unlocking methods (TPM, SmartCard) are not supported. + +=== OPEN +*open --type bitlk <device> <name>* + +bitlkOpen <device> <name> (*old syntax*) + +Opens the BITLK (a BitLocker-compatible) <device> and sets up a mapping +<name>. + +See *cryptsetup-open*(8). + +=== DUMP +*bitlkDump <device>* + +Dump the header information of a BITLK device. + +See *cryptsetup-bitlkDump*(8). + +Please note that cryptsetup does not use any Windows BitLocker code, +please report all problems related to this compatibility extension to +the cryptsetup project. + +== FVAULT2 (Apple macOS FileVault2 compatible) EXTENSION + +cryptsetup supports the mapping of FileVault2 (FileVault2 full-disk +encryption) by Apple for the macOS operating system using a native Linux +kernel API. + +*NOTE:* cryptsetup supports only FileVault2 based on Core Storage and HFS+ +filesystem (introduced in MacOS X 10.7 Lion). +It does NOT support the new version of FileVault based on the APFS +filesystem used in recent macOS versions. + +Header formatting and FVAULT2 header changes are not supported; +cryptsetup never changes the FVAULT2 header on-device. + +FVAULT2 extension requires kernel userspace crypto API to be available +(for details, see TCRYPT section) and kernel driver for HFS+ (hfsplus) +filesystem. + +Cryptsetup should recognize the basic configuration for portable drives. + +The *fvault2Dump* command should work for all recognized FVAULT2 devices +and doesn't require superuser privilege. + +For unlocking with the *open*, a password must be provided. +Other unlocking methods are not supported. + +=== OPEN +*open --type fvault2 <device> <name>* + +fvault2Open <device> <name> (*old syntax*) + +Opens the FVAULT2 (a FileVault2-compatible) <device> (usually the second +partition on the device) and sets up a mapping <name>. + +See *cryptsetup-open*(8). + +=== DUMP +*fvault2Dump <device>* + +Dump the header information of an FVAULT2 device. + +See *cryptsetup-fvault2Dump*(8). + +Note that cryptsetup does not use any macOS code or proprietary +specifications. Please report all problems related to this compatibility +extension to the cryptsetup project. + +== MISCELLANEOUS ACTIONS + +=== REPAIR +*repair <device>* + +Tries to repair the device metadata if possible. Currently supported +only for LUKS device type. + +See *cryptsetup-repair*(8). + +=== BENCHMARK +*benchmark <options>* + +Benchmarks ciphers and KDF (key derivation function). + +See *cryptsetup-benchmark*(8). + +== PLAIN DM-CRYPT OR LUKS? + +Unless you understand the cryptographic background well, use LUKS. With +plain dm-crypt there are a number of possible user errors that massively +decrease security. While LUKS cannot fix them all, it can lessen the +impact for many of them. + +== WARNINGS + +A lot of good information on the risks of using encrypted storage, on +handling problems and on security aspects can be found in the +Cryptsetup FAQ. Read it. Nonetheless, some risks deserve to be +mentioned here. + +*Backup:* Storage media die. Encryption has no influence on that. Backup +is mandatory for encrypted data as well, if the data has any worth. See +the Cryptsetup FAQ for advice on how to do a backup of an encrypted +volume. + +*Character encoding:* If you enter a passphrase with special symbols, +the passphrase can change depending on character encoding. Keyboard +settings can also change, which can make blind input hard or impossible. +For example, switching from some ASCII 8-bit variant to UTF-8 can lead +to a different binary encoding and hence different passphrase seen by +cryptsetup, even if what you see on the terminal is exactly the same. It +is therefore highly recommended to select passphrase characters only +from 7-bit ASCII, as the encoding for 7-bit ASCII stays the same for all +ASCII variants and UTF-8. + +*LUKS header:* If the header of a LUKS volume gets damaged, all data is +permanently lost unless you have a header-backup. If a key-slot is +damaged, it can only be restored from a header-backup or if another +active key-slot with known passphrase is undamaged. Damaging the LUKS +header is something people manage to do with surprising frequency. This +risk is the result of a trade-off between security and safety, as LUKS +is designed for fast and secure wiping by just overwriting header and +key-slot area. + +*Previously used partitions:* If a partition was previously used, it is +a very good idea to wipe filesystem signatures, data, etc. before +creating a LUKS or plain dm-crypt container on it. For a quick removal +of filesystem signatures, use *wipefs*(8). Take care though that this may +not remove everything. In particular, MD RAID signatures at the end of a +device may survive. It also does not remove data. For a full wipe, +overwrite the whole partition before container creation. If you do not +know how to do that, the cryptsetup FAQ describes several options. + +== EXAMPLES + +Example 1: Create LUKS 2 container on block device /dev/sdX.:: + sudo cryptsetup --type luks2 luksFormat /dev/sdX +Example 2: Add an additional passphrase to key slot 5.:: + sudo cryptsetup luksAddKey --key-slot 5 /dev/sdX +Example 3: Create LUKS header backup and save it to file.:: + sudo cryptsetup luksHeaderBackup /dev/sdX --header-backup-file + /var/tmp/NameOfBackupFile +Example 4: Open LUKS container on /dev/sdX and map it to sdX_crypt.:: + sudo cryptsetup open /dev/sdX sdX_crypt +*WARNING: The command in example 5 will erase all key slots.*:: + Your cannot use your LUKS container afterward anymore unless you have + a backup to restore. +Example 5: Erase all key slots on /dev/sdX.:: + sudo cryptsetup erase /dev/sdX +Example 6: Restore LUKS header from backup file.:: + sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file + /var/tmp/NameOfBackupFile + +== RETURN CODES + +Cryptsetup returns *0* on success and a non-zero value on error. + +Error codes are: *1* wrong parameters, *2* no permission (bad passphrase), +*3* out of memory, *4* wrong device specified, *5* device already exists +or device is busy. + +== NOTES + +=== Passphrase processing for PLAIN mode + +Note that no iterated hashing or salting is done in plain mode. If +hashing is done, it is a single direct hash. This means that low-entropy +passphrases are easy to attack in plain mode. + +*From a terminal*: The passphrase is read until the first newline, i.e. +'\n'. The input without the newline character is processed with the +default hash or the hash specified with --hash. The hash result will be +truncated to the key size of the used cipher, or the size specified with +-s. + +*From stdin*: Reading will continue until a newline (or until the +maximum input size is reached), with the trailing newline stripped. The +maximum input size is defined by the same compiled-in default as for the +maximum key file size and can be overwritten using --keyfile-size +option. + +The data read will be hashed with the default hash or the hash specified +with --hash. The hash result will be truncated to the key size of the +used cipher, or the size specified with -s. + +Note that if --key-file=- is used for reading the key from stdin, +trailing newlines are not stripped from the input. + +If "plain" is used as argument to --hash, the input data will not be +hashed. Instead, it will be zero padded (if shorter than the key size) +or truncated (if longer than the key size) and used directly as the +binary key. This is useful for directly specifying a binary key. No +warning will be given if the amount of data read from stdin is less than +the key size. + +*From a key file*: It will be truncated to the key size of the used +cipher or the size given by -s and directly used as a binary key. + +*WARNING*: The --hash argument is being ignored. The --hash option is +usable only for stdin input in plain mode. + +If the key file is shorter than the key, cryptsetup will quit with an +error. The maximum input size is defined by the same compiled-in default +as for the maximum key file size and can be overwritten using +--keyfile-size option. + +=== Passphrase processing for LUKS + +LUKS uses PBKDF to protect against dictionary attacks and to give some +protection to low-entropy passphrases (see cryptsetup FAQ). + +*From a terminal*: The passphrase is read until the first newline and +then processed by PBKDF2 without the newline character. + +*From stdin*: LUKS will read passphrases from stdin up to the first +newline character or the compiled-in maximum key file length. If +--keyfile-size is given, it is ignored. + +*From key file*: The complete keyfile is read up to the compiled-in +maximum size. Newline characters do not terminate the input. The +--keyfile-size option can be used to limit what is read. + +*Passphrase processing*: Whenever a passphrase is added to a LUKS header +(luksAddKey, luksFormat), the user may specify how much the time the +passphrase processing should consume. The time is used to determine the +iteration count for PBKDF2 and higher times will offer better protection +for low-entropy passphrases, but open will take longer to complete. For +passphrases that have entropy higher than the used key length, higher +iteration times will not increase security. + +The default setting of one or two seconds is sufficient for most +practical cases. The only exception is a low-entropy passphrase used on +a device with a slow CPU, as this will result in a low iteration count. +On a slow device, it may be advisable to increase the iteration time +using the --iter-time option in order to obtain a higher iteration +count. This does slow down all later luksOpen operations accordingly. + +=== Incoherent behavior for invalid passphrases/keys + +LUKS checks for a valid passphrase when an encrypted partition is +unlocked. The behavior of plain dm-crypt is different. It will always +decrypt with the passphrase given. If the given passphrase is wrong, the +device mapped by plain dm-crypt will essentially still contain encrypted +data and will be unreadable. + +=== Supported ciphers, modes, hashes and key sizes + +The available combinations of ciphers, modes, hashes and key sizes +depend on kernel support. See /proc/crypto for a list of available +options. You might need to load additional kernel crypto modules in +order to get more options. + +For the --hash option, if the crypto backend is libgcrypt, then all +algorithms supported by the gcrypt library are available. For other +crypto backends, some algorithms may be missing. + +=== Notes on passphrases + +Mathematics can't be bribed. Make sure you keep your passphrases safe. +There are a few nice tricks for constructing a fallback, when suddenly +out of the blue, your brain refuses to cooperate. These fallbacks need +LUKS, as it's only possible with LUKS to have multiple passphrases. +Still, if your attacker model does not prevent it, storing your +passphrase in a sealed envelope somewhere may be a good idea as well. + +=== Notes on Random Number Generators + +Random Number Generators (RNG) used in cryptsetup are always the kernel +RNGs without any modifications or additions to data stream produced. + +There are two types of randomness cryptsetup/LUKS needs. One type (which +always uses /dev/urandom) is used for salts, the AF splitter and for +wiping deleted keyslots. + +The second type is used for the volume key. You can switch between using +/dev/random and /dev/urandom here, see *--use-random* and +*--use-urandom* options. Using /dev/random on a system without enough +entropy sources can cause *luksFormat* to block until the requested +amount of random data is gathered. In a low-entropy situation (embedded +system), this can take a very long time and potentially forever. At the +same time, using /dev/urandom in a low-entropy situation will produce +low-quality keys. This is a serious problem, but solving it is out of +scope for a mere man-page. See *urandom(4)* for more information. + +=== Authenticated disk encryption (EXPERIMENTAL) + +Since Linux kernel version 4.12 dm-crypt supports authenticated disk +encryption. + +Normal disk encryption modes are length-preserving (plaintext sector is +of the same size as a ciphertext sector) and can provide only +confidentiality protection, but not cryptographically sound data +integrity protection. + +Authenticated modes require additional space per-sector for +authentication tag and use Authenticated Encryption with Additional Data +(AEAD) algorithms. + +If you configure LUKS2 device with data integrity protection, there will +be an underlying dm-integrity device, which provides additional +per-sector metadata space and also provide data journal protection to +ensure atomicity of data and metadata update. Because there must be +additional space for metadata and journal, the available space for the +device will be smaller than for length-preserving modes. + +The dm-crypt device then resides on top of such a dm-integrity device. +All activation and deactivation of this device stack is performed by +cryptsetup, there is no difference in using *luksOpen* for integrity +protected devices. If you want to format LUKS2 device with data +integrity protection, use *--integrity* option. + +Since dm-integrity doesn't support discards (TRIM), dm-crypt device on +top of it inherits this, so integrity protection mode doesn't support +discards either. + +Some integrity modes requires two independent keys (key for encryption +and for authentication). Both these keys are stored in one LUKS keyslot. + +*WARNING:* All support for authenticated modes is experimental and there +are only some modes available for now. Note that there are a very few +authenticated encryption algorithms that are suitable for disk +encryption. You also cannot use CRC32 or any other non-cryptographic +checksums (other than the special integrity mode "none"). If for some +reason you want to have integrity control without using authentication +mode, then you should separately configure dm-integrity independently of +LUKS2. + +=== Notes on loopback device use + +Cryptsetup is usually used directly on a block device (disk partition or +LVM volume). However, if the device argument is a file, cryptsetup tries +to allocate a loopback device and map it into this file. This mode +requires Linux kernel 2.6.25 or more recent which supports the loop +autoclear flag (loop device is cleared on the last close automatically). +Of course, you can always map a file to a loop-device manually. See the +cryptsetup FAQ for an example. + +When device mapping is active, you can see the loop backing file in the +status command output. Also see losetup(8). + +=== LUKS2 header locking + +The LUKS2 on-disk metadata is updated in several steps and to achieve +proper atomic update, there is a locking mechanism. For an image in +file, code uses *flock(2)* system call. For a block device, lock is +performed over a special file stored in a locking directory (by default +*/run/cryptsetup*). The locking directory should be created with the +proper security context by the distribution during the boot-up phase. +Only LUKS2 uses locks, other formats do not use this mechanism. + +=== LUKS on-disk format specification + +For LUKS on-disk metadata specification see +https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification[*LUKS1*] and +https://gitlab.com/cryptsetup/LUKS2-docs[*LUKS2*]. + +== AUTHORS + +Cryptsetup is originally written by mailto:jana@saout.de[Jana Saout]. + +The LUKS extensions and original man page were written by +mailto:clemens@endorphin.org[Clemens Fruhwirth]. + +Man page extensions by mailto:gmazyland@gmail.com[Milan Broz]. + +Man page rewrite and extension by mailto:arno@wagner.name[Arno Wagner]. + +include::man/common_footer.adoc[] diff --git a/man/integritysetup.8.adoc b/man/integritysetup.8.adoc new file mode 100644 index 0000000..2aec1a6 --- /dev/null +++ b/man/integritysetup.8.adoc @@ -0,0 +1,334 @@ += integritysetup(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: integritysetup {release-version} +:man-linkstyle: pass:[blue R < >] + +== NAME + +integritysetup - manage dm-integrity (block level integrity) volumes + +== SYNOPSIS + +*integritysetup <action> [<options>] <action args>* + +== DESCRIPTION + +Integritysetup is used to configure dm-integrity managed device-mapper +mappings. + +Device-mapper integrity target provides read-write transparent integrity +checking of block devices. The dm-integrity target emulates an additional +data integrity field per-sector. You can use this additional field +directly with integritysetup utility, or indirectly (for authenticated +encryption) through cryptsetup. + +== BASIC ACTIONS + +Integritysetup supports these operations: + +=== FORMAT +*format <device>* + +Formats <device> (calculates space and dm-integrity superblock and wipes +the device). + +*<options>* can be [--data-device, --batch-mode, --no-wipe, +--journal-size, --interleave-sectors, --tag-size, --integrity, +--integrity-key-size, --integrity-key-file, --sector-size, +--progress-frequency, --progress-json]. + +=== OPEN +*open <device> <name>* + +create <name> <device> (*OBSOLETE syntax*) + +Open a mapping with <name> backed by device <device>. + +*<options>* can be [--data-device, --batch-mode, --journal-watermark, +--journal-commit-time, --buffer-sectors, --integrity, +--integrity-key-size, --integrity-key-file, --integrity-no-journal, +--integrity-recalculate, +--integrity-recalculate-reset,--integrity-recovery-mode, +--allow-discards]. + +=== CLOSE +*close <name>* + +remove <name> (*OBSOLETE syntax*) + +Removes existing mapping <name>. + +*<options>* can be [--deferred] or [--cancel-deferred] + +=== STATUS +*status <name>* + +Reports status for the active integrity mapping <name>. + +=== DUMP +*dump <device>* + +Reports parameters from on-disk stored superblock. + +=== RESIZE +*resize <name>* + +Resizes an active mapping <name>. + +If --size (in 512-bytes sectors) or --device-size are not specified, the +size is computed from the underlying device. After resize, the +*recalculating* flag is set. If --wipe flag is set and the size of the +device is increased, the newly added section will be wiped. + +Increasing the size of integrity volumes is available since the Linux +kernel version 5.7, shrinking should work on older kernels too. + +*<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. + +*--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-watermark PERCENT*:: +Journal watermark in percents. When the size of the journal exceeds +this watermark, the journal flush will be started. + +*--journal-commit-time MS*:: +Commit time in milliseconds. When this time passes (and no explicit +flush operation was issued), the journal is written. + +*--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. + +*--data-device <data_device>*:: +Specify a separate data device that contains existing data. The +<device> then will contain calculated integrity tags and journal for +data on <data_device>. ++ +*NOTE:* To not wipe the data device after initial format, also specify +--no-wipe option and activate with --integrity-recalculate to +automatically recalculate integrity tags. + +*--sector-size, -s BYTES*:: +Sector size (power of two: 512, 1024, 2048, 4096). + +*--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. + +*--integrity, -I ALGORITHM*:: +Use internal integrity calculation (standalone mode). The integrity +algorithm can be CRC (crc32c/crc32), non-cryptographic hash function +(xxhash64) or hash function (sha1, sha256). ++ +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 +is 1, the corresponding region's data and integrity tags are not +synchronized - if the machine crashes, the unsynchronized regions will +be recalculated. The bitmap mode is faster than the journal mode, +because we don't have to write the data twice, but it is also less +reliable, because if data corruption happens when the machine crashes, +it may not be detected. + +*--bitmap-sectors-per-bit SECTORS*:: +Number of 512-byte sectors per bitmap bit, the value must be power of +two. + +*--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-recovery-mode. -R*:: +Recovery mode (no journal, no tag checking). + +*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)*. + +*--journal-integrity ALGORITHM*:: +Integrity algorithm for journal area. See --integrity option for +detailed specification. + +*--journal-integrity-key-size BYTES*:: +The size of the journal integrity key. Maximum is 4096 bytes. + +*--journal-integrity-key-file FILE*:: +The file with the integrity key. + +*--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. + +*--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. + +*--allow-discards*:: +Allow the use of discard (TRIM) requests for the device. This option +is available since the Linux kernel version 5.7. + +*--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. + +*--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. + +== LEGACY COMPATIBILITY OPTIONS + +*WARNING:*:: +Do not use these options until you need compatibility with specific +old kernel. + +*--integrity-legacy-padding*:: +Use inefficient legacy padding. + +*--integrity-legacy-hmac*:: +Use old flawed HMAC calculation (also does not protect superblock). + +*--integrity-legacy-recalculate*:: +Allow insecure recalculating of volumes with HMAC keys (recalculation +offset in superblock is not protected). + +== RETURN CODES + +Integritysetup returns *0* on success and a non-zero value on error. + +Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory, +*4* wrong device specified, *5* device already exists or device is busy. + +== NOTES +The dm-integrity target is available since Linux kernel version 4.12. + +Format and activation of an integrity device always require superuser +privilege because the superblock is calculated and handled in +dm-integrity kernel target. + +== EXAMPLES + +Format the device with default standalone mode (CRC32C): + +*integritysetup format <device>* + +Open the device with default parameters: + +*integritysetup open <device> test* + +Format the device in standalone mode for use with HMAC(SHA256): + +*integritysetup format <device> --tag-size 32 --integrity hmac-sha256 +--integrity-key-file <keyfile> --integrity-key-size <key_bytes>* + +Open (activate) the device with HMAC(SHA256) and HMAC key in file: + +*integritysetup open <device> test --integrity hmac-sha256 +--integrity-key-file <keyfile> --integrity-key-size <key_bytes>* + +Dump dm-integrity superblock information: + +*integritysetup dump <device>* + +== DM-INTEGRITY ON-DISK FORMAT + +The on-disk format specification available at +https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity[*DMIntegrity*] page. + +== AUTHORS + +The integritysetup tool is written by mailto:gmazyland@gmail.com[Milan Broz]. + +include::man/common_footer.adoc[] diff --git a/man/veritysetup.8.adoc b/man/veritysetup.8.adoc new file mode 100644 index 0000000..36d1501 --- /dev/null +++ b/man/veritysetup.8.adoc @@ -0,0 +1,311 @@ += veritysetup(8) +:doctype: manpage +:manmanual: Maintenance Commands +:mansource: veritysetup {release-version} +:man-linkstyle: pass:[blue R < >] + +== NAME + +veritysetup - manage dm-verity (block level verification) volumes + +== SYNOPSIS + +*veritysetup <action> [<options>] <action args>* + +== DESCRIPTION + +Veritysetup is used to configure dm-verity managed device-mapper +mappings. + +Device-mapper verity target provides read-only transparent integrity +checking of block devices using kernel crypto API. + +The dm-verity devices are always read-only. + +== BASIC ACTIONS + +Veritysetup supports these operations: + +=== FORMAT +*format <data_device> <hash_device>* + +Calculates and permanently stores hash verification data for +data_device. Hash area can be located on the same device after data if +specified by --hash-offset option. + +Note you need to provide root hash string for device verification or +activation. Root hash must be trusted. + +The data or hash device argument can be block device or file image. If +hash device path doesn't exist, it will be created as file. + +*<options>* can be [--hash, --no-superblock, --format, +--data-block-size, --hash-block-size, --data-blocks, --hash-offset, +--salt, --uuid, --root-hash-file]. + +If option --root-hash-file is used, the root hash is stored in +hex-encoded text format in <path>. + +=== OPEN +*open <data_device> <name> <hash_device> <root_hash>* + +*open <data_device> <name> <hash_device> --root-hash-file <path>* + +create <name> <data_device> <hash_device> <root_hash> (*OBSOLETE syntax*) + +Creates a mapping with <name> backed by device <data_device> and using +<hash_device> for in-kernel verification. + +The <root_hash> is a hexadecimal string. + +*<options>* can be [--hash-offset, --no-superblock, --ignore-corruption +or --restart-on-corruption, --panic-on-corruption, --ignore-zero-blocks, +--check-at-most-once, --root-hash-signature, --root-hash-file, --use-tasklets]. + +If option --root-hash-file is used, the root hash is read from <path> +instead of from the command line parameter. Expects hex-encoded text, +without terminating newline. + +If option --no-superblock is used, you have to use as the same options +as in initial format operation. + +=== VERIFY +*verify <data_device> <hash_device> <root_hash>* + +*verify <data_device> <hash_device> --root-hash-file <path>* + +Verifies data on data_device with use of hash blocks stored on +hash_device. + +This command performs userspace verification, no kernel device is +created. + +The <root_hash> is a hexadecimal string. + +If option --root-hash-file is used, the root hash is read from <path> +instead of from the command line parameter. Expects hex-encoded text, +without terminating newline. + +*<options>* can be [--hash-offset, --no-superblock, --root-hash-file]. + +If option --no-superblock is used, you have to use as the same options +as in initial format operation. + +=== CLOSE +*close <name>* + +remove <name> (*OBSOLETE syntax*) + +Removes existing mapping <name>. + +*<options>* can be [--deferred] or [--cancel-deferred]. + +=== STATUS +*status <name>* + +Reports status for the active verity mapping <name>. + +=== DUMP +*dump <hash_device>* + +Reports parameters of verity device from on-disk stored superblock. + +*<options>* can be [--hash-offset]. + +== OPTIONS + +*--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. + +*--check-at-most-once*:: +Instruct kernel to verify blocks only the first time they are read +from the data device, rather than every time. ++ +*WARNING:* It provides a reduced level of security because only offline +tampering of the data device's content will be detected, not online +tampering. This option is available since Linux kernel version 4.17. + +*--hash=hash*:: +Hash algorithm for dm-verity. For default see --help option. + +*--fec-device=fec_device*:: +Use forward error correction (FEC) to recover from corruption if hash +verification fails. Use encoding data from the specified device. ++ +The fec device argument can be block device or file image. For format, +if fec device path doesn't exist, it will be created as file. ++ +Block sizes for data and hash devices must match. Also, if the verity +data_device is encrypted the fec_device should be too. ++ +FEC calculation covers data, hash area, and optional foreign metadata +stored on the same device with the hash tree (additional space after +hash area). Size of this optional additional area protected by FEC is +calculated from image sizes, so you must be sure that you use the same +images for activation. ++ +If the hash device is in a separate image, metadata covers the whole +rest of the image after the hash area. ++ +If hash and FEC device is in the image, metadata ends on the FEC area +offset. + +*--fec-offset=bytes*:: +This is the offset, in bytes, from the start of the FEC device to the +beginning of the encoding data. + +*--fec-roots=num*:: +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). + +*--root-hash-file=FILE*:: +Path to file with stored root hash in hex-encoded text. + +*--root-hash-signature=FILE*:: +Path to root hash signature file used to verify the root hash (in +kernel). This feature requires Linux kernel version 5.4 or more +recent. + +*--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. + +*--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. + +Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory, +*4* wrong device specified, *5* device already exists or device is busy. + +== EXAMPLES + +*veritysetup --data-blocks=256 format <data_device> <hash_device>* + +Calculates and stores verification data on hash_device for the first 256 +blocks (of block-size). If hash_device does not exist, it is created (as +file image). + +*veritysetup format --root-hash-file <path> <data_device> <hash_device>* + +Calculates and stores verification data on hash_device for the whole +data_device, and store the root hash as hex-encoded text in <path>. + +*veritysetup --data-blocks=256 --hash-offset=1052672 format <device> +<device>* + +Verification data (hashes) is stored on the same device as data +(starting at hash-offset). Hash-offset must be greater than number of +blocks in data-area. + +*veritysetup --data-blocks=256 --hash-offset=1052672 create test-device +<device> <device> <root_hash>* + +Activates the verity device named test-device. Options --data-blocks and +--hash-offset are the same as in the format command. The <root_hash> was +calculated in format command. + +*veritysetup --data-blocks=256 --hash-offset=1052672 verify +<data_device> <hash_device> <root_hash>* + +Verifies device without activation (in userspace). + +*veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file +<path> verify <data_device> <hash_device>* + +Verifies device without activation (in userspace). Root hash passed via +a file rather than inline. + +*veritysetup --fec-device=<fec_device> --fec-roots=10 format +<data_device> <hash_device>* + +Calculates and stores verification and encoding data for data_device. + +== DM-VERITY ON-DISK SPECIFICATION + +The on-disk format specification is available at +https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[*DMVerity*] page. + +== AUTHORS + +The first implementation of veritysetup was written by Chrome OS +authors. + +This version is based on verification code written by +mailto:mpatocka@redhat.com[Mikulas Patocka] and rewritten for libcryptsetup +by mailto:gmazyland@gmail.com[Milan Broz]. + +include::man/common_footer.adoc[] |