diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makemodule.am | 15 | ||||
| -rw-r--r-- | man/cryptsetup-reencrypt.8 | 291 | ||||
| -rw-r--r-- | man/cryptsetup.8 | 1535 | ||||
| -rw-r--r-- | man/integritysetup.8 | 221 | ||||
| -rw-r--r-- | man/veritysetup.8 | 228 |
5 files changed, 2290 insertions, 0 deletions
diff --git a/man/Makemodule.am b/man/Makemodule.am new file mode 100644 index 0000000..3f68441 --- /dev/null +++ b/man/Makemodule.am @@ -0,0 +1,15 @@ +EXTRA_DIST += man/cryptsetup.8 man/integritysetup.8 man/veritysetup.8 man/cryptsetup-reencrypt.8 + +man8_MANS += man/cryptsetup.8 + +if VERITYSETUP +man8_MANS += man/veritysetup.8 +endif + +if REENCRYPT +man8_MANS += man/cryptsetup-reencrypt.8 +endif + +if INTEGRITYSETUP +man8_MANS += man/integritysetup.8 +endif diff --git a/man/cryptsetup-reencrypt.8 b/man/cryptsetup-reencrypt.8 new file mode 100644 index 0000000..0ebb38c --- /dev/null +++ b/man/cryptsetup-reencrypt.8 @@ -0,0 +1,291 @@ +.TH CRYPTSETUP-REENCRYPT "8" "January 2019" "cryptsetup-reencrypt" "Maintenance Commands" +.SH NAME +cryptsetup-reencrypt - tool for offline LUKS device re-encryption +.SH SYNOPSIS +.B cryptsetup-reencrypt <options> <device> +.SH DESCRIPTION +.PP +Cryptsetup-reencrypt can be used to change reencryption parameters +which otherwise require full on-disk data change (re-encryption). + +You can regenerate \fBvolume key\fR (the real key used in on-disk encryption +unclocked by passphrase), \fBcipher\fR, \fBcipher mode\fR. + +Cryptsetup-reencrypt reencrypts data on LUKS device in-place. During +reencryption process the LUKS device is marked unavailable. + +\fIWARNING\fR: The cryptsetup-reencrypt program is not resistant to hardware +or kernel failures during reencryption (you can lose your data in this case). + +\fIALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL.\fR +.br +The reencryption can be temporarily suspended (by TERM signal or by +using ctrl+c) but you need to retain temporary files named LUKS-<uuid>.[log|org|new]. +LUKS device is unavailable until reencryption is finished though. + +Current working directory must be writable and temporary +files created during reencryption must be present. + +For more info about LUKS see cryptsetup(8). +.PP +.SH OPTIONS +.TP +To start (or continue) re-encryption for <device> use: +.PP +\fIcryptsetup-reencrypt\fR <device> + +\fB<options>\fR can be [\-\-batch-mode, \-\-block-size, \-\-cipher | \-\-keep-key, +\-\-debug, \-\-device-size, \-\-hash, \-\-header, \-\-iter-time | \-\-pbkdf\-force\-iterations, +\-\-key-file, \-\-key-size, \-\-key-slot, \-\-keyfile-offset, \-\-keyfile-size, +\-\-master\-key\-file, \-\-tries, \-\-pbkdf, \-\-pbkdf\-memory, \-\-pbkdf\-parallel, +\-\-progress-frequency, \-\-use-directio, \-\-use-random | \-\-use-urandom, \-\-use-fsync, +\-\-uuid, \-\-verbose, \-\-write-log] + +To encrypt data on (not yet encrypted) device, use \fI\-\-new\fR with combination +with \fI\-\-reduce-device-size\fR or with \fI\-\-header\fR option for detached header. + +To remove encryption from device, use \fI\-\-decrypt\fR. + +For detailed description of encryption and key file options see \fIcryptsetup(8)\fR +man page. +.TP +.B "\-\-batch-mode, \-q" +Suppresses all warnings and reencryption progress output. +.TP +.B "\-\-block-size, \-B \fIvalue\fR" +Use re-encryption block size of <value> in MiB. + +Values can be between 1 and 64 MiB. +.TP +.B "\-\-cipher, \-c" \fI<cipher-spec>\fR +Set the cipher specification string. +.TP +.B "\-\-debug" +Run in debug mode with full diagnostic logs. Debug output +lines are always prefixed by '#'. +.TP +.B "\-\-decrypt" +Remove encryption (decrypt already encrypted device and remove LUKS header). + +\fBWARNING:\fR This is destructive operation and cannot be reverted. +.TP +.B "\-\-device-size \fIsize[units]\fR" +Instead of real device size, use specified value. + +It means that only specified area (from the start of the device +to the specified size) will be reencrypted. + +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). + +\fBWARNING:\fR This is destructive operation. +.TP +.B "\-\-hash, \-h \fI<hash-spec>\fR" +Specifies the hash used in the LUKS1 key setup scheme and volume key digest. + +\fBNOTE:\fR if this parameter is not specified, default hash algorithm is always used +for new LUKS1 device header. + +\fBNOTE:\fR with LUKS2 format this option is only relevant when new keyslot pbkdf algorithm +is set to PBKDF2 (see \fI\-\-pbkdf\fR). +.TP +.B "\-\-header\fR \fI<LUKS header file>\fR" +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. + +\fBWARNING:\fR There is no check whether the ciphertext device specified +actually belongs to the header given. +If used with \fI\-\-new\fR option, the header file will created (or overwritten). +Use with care. +.TP +.B "\-\-iter-time, \-i \fI<milliseconds>\fR" +The number of milliseconds to spend with PBKDF2 passphrase processing for the +new LUKS header. +.TP +.B "\-\-keep-key" +Do not change encryption key, just reencrypt the LUKS header and keyslots. + +This option can be combined only with \fI\-\-hash\fR, \fI\-\-iter-time\fR, +\fI\-\-pbkdf\-force\-iterations\fR, \fI\-\-pbkdf\fR (LUKS2 only), +\fI\-\-pbkdf\-memory\fR (Argon2i/id and LUKS2 only) and \fI\-\-pbkdf\-parallel\fR +(Argon2i/id and LUKS2 only) options. +.TP +.B "\-\-key-file, \-d \fIname\fR" +Read the passphrase from file. + +\fBWARNING:\fR \-\-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-reencrypt will ask for all active keyslot +passphrases. +.TP +.B "\-\-key-size, \-s \fI<bits>\fR" +Set 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. + +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. +.TP +.B "\-\-key-slot, \-S <0-MAX>" +Specify which key slot is used. For LUKS1, max keyslot number is 7. For LUKS2, it's 31. + +\fBWARNING:\fR All other keyslots will be disabled if this option is used. +.TP +.B "\-\-keyfile-offset \fIvalue\fR" +Skip \fIvalue\fR bytes at the beginning of the key file. +.TP +.B "\-\-keyfile-size, \-l" +Read a maximum of \fIvalue\fR bytes from the key file. +Default is to read the whole file up to the compiled-in +maximum. +.TP +.B "\-\-master\-key\-file" +Use new volume (master) key stored in a file. +.TP +.B "\-\-new, \-N" +Create new header (encrypt not yet encrypted device). + +This option must be used together with \-\-reduce-device-size. + +\fBWARNING:\fR This is destructive operation and cannot be reverted. +.TP +.B "\-\-pbkdf" +Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot. +The PBKDF can be: \fIpbkdf2\fR, \fIargon2i\fR for Argon2i or \fIargon2id\fR for Argon2id. + +For LUKS1, only \fIpbkdf2\fR is accepted (no need to use this option). +.TP +.B "\-\-pbkdf\-force\-iterations <num>" +Avoid PBKDF benchmark and set time cost (iterations) directly. +.TP +.B "\-\-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. +.TP +.B "\-\-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. +.TP +.B "\-\-progress-frequency <seconds>" +Print separate line every <seconds> with reencryption progress. +.TP +.B "\-\-reduce-device-size \fIsize[units]\fR" +Enlarge data offset to specified value by shrinking device size. + +This means that last sectors on the original device will be lost, +ciphertext data will be effectively shifted by specified +number of sectors. + +It can be useful if you e.g. added some space to underlying +partition (so last sectors contains no data). + +For units suffix see \-\-device-size parameter description. + +You cannot shrink device more than by 64 MiB (131072 sectors). + +\fBWARNING:\fR This is destructive operation and cannot be reverted. +Use with extreme care - shrunk filesystems are usually unrecoverable. +.TP +.B "\-\-tries, \-T" +Number of retries for invalid passphrase entry. +.TP +.B "\-\-type <type>" +Use only while encrypting not yet encrypted device (see \-\-new). + +Specify LUKS version when performing in-place encryption. If the parameter +is omitted default value (LUKS1) is used. Type may be one of: \fBluks\fR (default), +\fBluks1\fR or \fBluks2\fR. +.TP +.B "\-\-use-directio" +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). +.TP +.B "\-\-use-fsync" +Use fsync call after every written block. This applies for reencryption +log files as well. +.TP +.B "\-\-use-random" +.TP +.B "\-\-use-urandom" +Define which kernel random number generator will be used to create the volume key. +.TP +.B "\-\-uuid" \fI<uuid>\fR +Use only while resuming an interrupted decryption process (see \-\-decrypt). + +To find out what \fI<uuid>\fR to pass look for temporary files LUKS-<uuid>.[|log|org|new] +of the interrupted decryption process. +.TP +.B "\-\-verbose, \-v" +Print more information on command execution. +.TP +.B "\-\-version" +Show the program version. +.TP +.B "\-\-write-log" +Update log file after every block write. This can slow down reencryption +but will minimize data loss in the case of system crash. + +.SH RETURN CODES +Cryptsetup-reencrypt 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. +.SH EXAMPLES +.TP +Reencrypt /dev/sdb1 (change volume key) +cryptsetup-reencrypt /dev/sdb1 +.TP +Reencrypt and also change cipher and cipher mode +cryptsetup-reencrypt /dev/sdb1 \-c aes-xts-plain64 +.TP +Add LUKS encryption to not yet encrypted device + +First, be sure you have space added to disk. + +Or alternatively shrink filesystem in advance. +.br +Here we need 4096 512-bytes sectors (enough for 2x128 bit key). + +fdisk \-u /dev/sdb # move sdb1 partition end + 4096 sectors +(or use resize2fs or tool for your filesystem and shrink it) + +cryptsetup-reencrypt /dev/sdb1 \-\-new \-\-reduce-device-size 4096S +.TP +Remove LUKS encryption completely + +cryptsetup-reencrypt /dev/sdb1 \-\-decrypt + +.SH REPORTING BUGS +Report bugs, including ones in the documentation, on +the cryptsetup mailing list at <dm-crypt@saout.de> +or in the 'Issues' section on LUKS website. +Please attach the output of the failed command with the +\-\-debug option added. +.SH AUTHORS +Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>. +.SH COPYRIGHT +Copyright \(co 2012-2019 Milan Broz +.br +Copyright \(co 2012-2019 Red Hat, Inc. + +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH SEE ALSO +The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR diff --git a/man/cryptsetup.8 b/man/cryptsetup.8 new file mode 100644 index 0000000..3c5b93a --- /dev/null +++ b/man/cryptsetup.8 @@ -0,0 +1,1535 @@ +.TH CRYPTSETUP "8" "January 2019" "cryptsetup" "Maintenance Commands" +.SH NAME +cryptsetup - manage plain dm-crypt and LUKS encrypted volumes +.SH SYNOPSIS +.B cryptsetup <options> <action> <action args> +.SH DESCRIPTION +.PP +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 and for TrueCrypt compatible volumes. + +.SH PLAIN DM-CRYPT OR LUKS? +.PP +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. +.SH WARNINGS +.PP +A lot of good information on the risks of using encrypted storage, +on handling problems and on security aspects can be found in the +\fICryptsetup FAQ\fR. Read it. Nonetheless, some risks deserve +to be mentioned here. + +\fBBackup:\fR 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. + +\fBCharacter encoding:\fR 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. + +\fBLUKS header:\fR 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. + +\fBPreviously used partitions:\fR 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". 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. + +.SH BASIC COMMANDS +The following are valid actions for all supported device types. + +\fIopen\fR <device> <name> \-\-type <device_type> +.IP +Opens (creates a mapping with) <name> backed by device <device>. + +Device type can be \fIplain\fR, \fIluks\fR (default), \fIluks1\fR, \fIluks2\fR, +\fIloopaes\fR or \fItcrypt\fR. + +For backward compatibility there are \fBopen\fR command aliases: + +\fBcreate\fR (argument-order <name> <device>): open \-\-type plain +.br +\fBplainOpen\fR: open \-\-type plain +.br +\fBluksOpen\fR: open \-\-type luks +.br +\fBloopaesOpen\fR: open \-\-type loopaes +.br +\fBtcryptOpen\fR: open \-\-type tcrypt + +\fB<options>\fR are type specific and are described below +for individual device types. For \fBcreate\fR, the order of the <name> +and <device> options is inverted for historical reasons, all other +aliases use the standard \fB<device> <name>\fR order. +.PP +\fIclose\fR <name> +.IP +Removes the existing mapping <name> and wipes the key from kernel memory. + +For backward compatibility there are \fBclose\fR command aliases: +\fBremove\fR, \fBplainClose\fR, \fBluksClose\fR, \fBloopaesClose\fR, +\fBtcryptClose\fR (all behaves exactly the same, device type is +determined automatically from active device). + +\fB<options>\fR can be [\-\-deferred] + +.PP +\fIstatus\fR <name> +.IP +Reports the status for the mapping <name>. +.PP +\fIresize\fR <name> +.IP +Resizes an active mapping <name>. + +If \-\-size (in 512-bytes sectors) is not specified, the size is computed +from the underlying device. For LUKS it is the size of the +underlying device without the area reserved for LUKS header +(see data payload offset in \fBluksDump\fR 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 and 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. + +With LUKS2 device additional \fB<options>\fR can be [\-\-token\-id, \-\-token\-only, +\-\-key\-slot, \-\-key\-file, \-\-keyfile\-size, \-\-keyfile\-offset, \-\-timeout, +\-\-disable\-locks, \-\-disable\-keyring]. + +.PP +\fIrefresh\fR <name> +.IP +Refreshes parameters of active mapping <name>. + +Updates parameters of active device <name> without need to deactivate the device +(and umount filesystem). Currently it supports parameters refresh on following +devices: LUKS1, LUKS2 (including authenticated encryption), plain crypt +and loopaes. + +Mandatory parametrs are identical to those of an open action for respective +device type. + +You may change following parameters on all devices \-\-perf\-same_cpu_crypt, +\-\-perf\-submit_from_crypt_cpus and \-\-allow\-discards. + +Refreshing device without any optional parameter will refresh the device +with default setting (respective to device type). + +\fBLUKS2 only:\fR + +\-\-integrity\-no\-journal parameter affects only LUKS2 devices with +underlying dm-integrity device. + +Adding option \-\-persistent stores any combination of device parameters +above in LUKS2 metadata (only after successful refresh operation). + +\-\-disable\-keyring parameter refreshes a device with volume key passed +in dm-crypt driver. + +.SH 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: + +\fIopen\fR \-\-type plain <device> <name> +.br +\fIcreate\fR <name> <device> (\fBOBSOLETE syntax\fR) +.IP +Opens (creates a mapping with) <name> backed by device <device>. + +\fB<options>\fR can be [\-\-hash, \-\-cipher, \-\-verify-passphrase, +\-\-sector\-size, \-\-key-file, \-\-keyfile-offset, \-\-key-size, +\-\-offset, \-\-skip, \-\-size, \-\-readonly, \-\-shared, \-\-allow\-discards, +\-\-refresh] + +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. +.SH 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 PBKDF2, which implements hash iteration and salting +in one function. + +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 +\fI\-\-type luks2\fR in \fIluksFormat\fR command. +For activation, the format is already recognized automatically. + +Each passphrase, also called a +.B 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 \fB<device>\fR 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 \fB\-\-header\fR parameter can be used +in all LUKS commands and always takes precedence over the positional +\fB<device>\fR parameter. + +The following are valid LUKS actions: + +\fIluksFormat\fR <device> [<key file>] +.IP +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 can only call luksFormat on a LUKS device that is not mapped. + +To use LUKS2, specify \fI\-\-type luks2\fR. + +\fB<options>\fR 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, \-\-master\-key\-file, \-\-iter\-time, \-\-header, +\-\-pbkdf\-force\-iterations, +\-\-force\-password, \-\-disable-locks]. + +For LUKS2, additional \fB<options>\fR 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]. + +\fBWARNING:\fR Doing a luksFormat on an existing LUKS container will +make all data the old container permanently irretrievable unless +you have a header backup. +.PP +\fIopen\fR \-\-type luks <device> <name> +.br +\fIluksOpen\fR <device> <name> (\fBold syntax\fR) +.IP +Opens the LUKS device <device> and sets up a mapping <name> after +successful verification of the supplied passphrase. + +First, the passphrase is searched in LUKS tokens. If it's not +found in any token and also the passphrase is not supplied via \-\-key-file, +the command prompts for it interactively. + +\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset, +\-\-keyfile\-size, \-\-readonly, \-\-test\-passphrase, +\-\-allow\-discards, \-\-header, \-\-key-slot, \-\-master\-key\-file, \-\-token\-id, +\-\-token\-only, \-\-disable\-keyring, \-\-disable\-locks, \-\-type, \-\-refresh]. +.PP +\fIluksSuspend\fR <name> +.IP +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 \fIluksResume\fR to reinstate +the encryption key and unblock the device or \fIclose\fR to remove +the mapped device. + +\fBWARNING:\fR never suspend the device on which the cryptsetup binary resides. + +\fB<options>\fR can be [\-\-header, \-\-disable\-locks]. +.PP +\fIluksResume\fR <name> +.IP +Resumes a suspended device and reinstates the encryption key. +Prompts interactively for a passphrase if \-\-key-file is not given. + +\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-size, \-\-header, +\-\-disable\-keyring, \-\-disable\-locks, \-\-type] +.PP +\fIluksAddKey\fR <device> [<key file with new key>] +.IP +Adds a new passphrase. An existing passphrase must be supplied +interactively or via \-\-key-file. +The new passphrase to be added can be specified interactively +or read from the file given as positional argument. + +\fBNOTE:\fR 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 \-\-master\-key\-file option, +new random key is generated. Existing passphrase for any active keyslot +is not required. + +\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset, +\-\-keyfile\-size, \-\-new\-keyfile\-offset, +\-\-new\-keyfile\-size, \-\-key\-slot, \-\-master\-key\-file, +\-\-iter\-time, \-\-force\-password, \-\-header, \-\-disable\-locks, +\-\-unbound, \-\-type, \-\-keyslot\-cipher, \-\-keyslot\-key\-size]. +.PP +\fIluksRemoveKey\fR <device> [<key file with passphrase to be removed>] +.IP +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. + +\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset, +\-\-keyfile\-size, \-\-header, \-\-disable\-locks, \-\-type] + +\fBWARNING:\fR 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. +.PP +\fIluksChangeKey\fR <device> [<new key file>] +.IP +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 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. + +\fBWARNING:\fR 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. + +\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset, +\-\-keyfile\-size, \-\-new\-keyfile\-offset, +\-\-new\-keyfile\-size, \-\-key\-slot, \-\-force\-password, \-\-header, +\-\-disable\-locks, \-\-type, \-\-keyslot\-cipher, \-\-keyslot\-key\-size]. +.PP +.PP +\fIluksConvertKey\fR <device> +.IP +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. + +\fBWARNING:\fR 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. + +\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset, +\-\-keyfile\-size, \-\-key\-slot, \-\-header, \-\-disable\-locks, +\-\-iter-time, \-\-pbkdf, \-\-pbkdf\-force\-iterations, +\-\-pbkdf\-memory, \-\-pbkdf\-parallel, +\-\-keyslot\-cipher, \-\-keyslot\-key\-size]. +.PP +\fIluksKillSlot\fR <device> <key slot number> +.IP +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. + +\fB<options>\fR can be [\-\-key\-file, \-\-keyfile\-offset, +\-\-keyfile\-size, \-\-header, \-\-disable\-locks, \-\-type]. + +\fBWARNING:\fR 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. + +\fBNOTE:\fR 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. + +.PP +\fIerase\fR <device> +.br +\fIluksErase\fR <device> +.IP +Erase all keyslots and make the LUKS container permanently inaccessible. +You do not need to provide any password for this operation. + +\fBWARNING:\fR This operation is irreversible. +.PP +\fIluksUUID\fR <device> +.IP +Print the UUID of a LUKS device. +.br +Set new UUID if \fI\-\-uuid\fR option is specified. +.PP +\fIisLuks\fR <device> +.IP +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. +.PP +\fIluksDump\fR <device> +.IP +Dump the header information of a LUKS device. + +If the \-\-dump\-master\-key option is used, the LUKS device master key is +dumped instead of the keyslot info. Together with \-\-master\-key\-file option, +master key is dumped to a file instead of standard output. Beware that the +master 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 master key is compromised, the whole device +has to be erased to prevent further access. Use this option carefully. + +To dump the master key, a passphrase has to be supplied, +either interactively or via \-\-key\-file. + +\fB<options>\fR can be [\-\-dump\-master\-key, \-\-key\-file, +\-\-keyfile\-offset, \-\-keyfile\-size, \-\-header, \-\-disable\-locks, +\-\-master\-key\-file, \-\-type]. + +\fBWARNING:\fR If \-\-dump\-master\-key is used with \-\-key\-file +and the argument to \-\-key\-file is '-', no validation question +will be asked and no warning given. +.PP +\fIluksHeaderBackup\fR <device> \-\-header\-backup\-file <file> +.IP +Stores a binary backup of the LUKS header and keyslot area. +.br +Note: Using '-' as filename writes the header backup to a file named '-'. + +\fBWARNING:\fR 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. +.PP +\fIluksHeaderRestore\fR <device> \-\-header\-backup\-file <file> +.IP +Restores a binary backup of the LUKS header and keyslot area +from the specified file. +.br +Note: Using '-' as filename reads the header backup from a file named '-'. + +\fBWARNING:\fR Header and keyslots will be replaced, only +the passphrases from the backup will work afterward. + +This command requires that the master 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. +.PP +\fItoken\fR <add|remove|import|export> <device> +.IP +Action \fIadd\fR creates 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 \fIuser\fR or +\fIuser-session\fR keyring. +The \fItoken\fR 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. + +\fBWARNING:\fR The action \fItoken remove\fR removes any token type, not just \fIkeyring\fR +type from token slot specified by \-\-token\-id option. + +Action \fIimport\fR 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 \fIexport\fR writes requested token json to a file passed with \-\-json\-file or +to standard output. + +\fB<options>\fR can be [\-\-header, \-\-token\-id, \-\-key\-slot, \-\-key\-description, +\-\-disable\-locks, \-\-disable\-keyring, \-\-json\-file]. +.PP +\fIconvert\fR <device> \-\-type <format> +.IP +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. + +\fB\-\-type\fR option is mandatory with following accepted values: \fIluks1\fR or \fIluks2\fR. + +\fBWARNING:\fR The \fIconvert\fR 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! + +\fB<options>\fR can be [\-\-header, \-\-type]. +.PP +\fIconfig\fR <device> +.IP +Set permanent configuration options (store to LUKS header). +The \fIconfig\fR command is supported only for LUKS2. + +The permanent options can be \fI\-\-priority\fR to set priority (normal, prefer, ignore) +for keyslot (specified by \fI\-\-key\-slot\fR) or \fI\-\-label\fR and \fI\-\-subsystem\fR. + +\fB<options>\fR can be [\-\-priority, \-\-label, \-\-subsystem, \-\-key\-slot, \-\-header]. + +.SH loop-AES EXTENSION +cryptsetup supports mapping loop-AES encrypted partition using +a compatibility mode. +.PP +\fIopen\fR \-\-type loopaes <device> <name> \-\-key\-file <keyfile> +.br +\fIloopaesOpen\fR <device> <name> \-\-key\-file <keyfile> (\fBold syntax\fR) +.IP +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: +.br +gpg \-\-decrypt <keyfile> | cryptsetup loopaesOpen \-\-key\-file=\- +<device> <name> + +\fBWARNING:\fR The loop-AES extension cannot use the direct input of key file +on real terminal because the keys are separated by end-of-line and only part +of the multi-key file would be read. +.br +If you need it in script, just use the pipe redirection: +.br +echo $keyfile | cryptsetup loopaesOpen \-\-key\-file=\- <device> <name> + +Use \fB\-\-keyfile\-size\fR to specify the proper key length if needed. + +Use \fB\-\-offset\fR to specify device offset. Note that the units +need to be specified in number of 512 byte sectors. + +Use \fB\-\-skip\fR 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 \fB\-\-skip 0\fR in addition to the offset +parameter. + +Use \fB\-\-hash\fR to override the default hash function for +passphrase hashing (otherwise it is detected according to key +size). + +\fB<options>\fR can be [\-\-key\-file, \-\-key\-size, \-\-offset, \-\-skip, +\-\-hash, \-\-readonly, \-\-allow\-discards, \-\-refresh]. +.PP +See also section 7 of the FAQ and \fBhttp://loop-aes.sourceforge.net\fR +for more information regarding loop-AES. +.SH TCRYPT (TrueCrypt-compatible and VeraCrypt) EXTENSION +cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt +(with \fB\-\-veracrypt\fR option) 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). + +To recognize a VeraCrypt device use the \fB\-\-veracrypt\fR option. +VeraCrypt is just extension of TrueCrypt header with increased +iteration count so unlocking can take quite a lot of time (in comparison +with TCRYPT device). + +To open a VeraCrypt device with a custom Personal Iteration Multiplier (PIM) +value, \fBadditionally to \-\-veracrypt \fR use either the +\fB\-\-veracrypt\-pim=<PIM>\fR option to directly specify the PIM on the command- +line or use \fB\-\-veracrypt\-query\-pim\fR to be prompted for the PIM. + +The PIM value affects the number of iterations applied during key derivation. Please refer to +\fBhttps://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html\fR +for more detailed information. + +\fBNOTE:\fR Activation with \fBtcryptOpen\fR is supported only for cipher chains +using LRW or XTS encryption modes. + +The \fBtcryptDump\fR 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 \fB\-\-tcrypt\-system\fR 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 (\fBlosetup \-P\fR, see \fPlosetup(8)\fR 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 \fB\-\-tcrypt\-hidden\fR option. + +To explicitly use backup (secondary) header, use \fB\-\-tcrypt\-backup\fR +option. + +\fBNOTE:\fR 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. + +.PP +\fIopen\fR \-\-type tcrypt <device> <name> +.br +\fItcryptOpen\fR <device> <name> (\fBold syntax\fR) +.IP +Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up +a mapping <name>. + +\fB<options>\fR can be [\-\-key\-file, \-\-tcrypt\-hidden, +\-\-tcrypt\-system, \-\-tcrypt\-backup, \-\-readonly, \-\-test\-passphrase, +\-\-allow-discards, \-\-veracrypt, \-\-veracrypt\-pim, \-\-veracrypt\-query\-pim]. + +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. + +\fBWARNING:\fR Option \fB\-\-allow\-discards\fR cannot be combined with +option \fB\-\-tcrypt\-hidden\fR. For normal mapping, it can cause +the \fBdestruction of hidden volume\fR (hidden volume appears as unused space +for outer volume so this space can be discarded). + +.PP +\fItcryptDump\fR <device> +.IP +Dump the header information of a TCRYPT device. + +If the \-\-dump\-master\-key option is used, the TCRYPT device master key +is dumped instead of TCRYPT header info. Beware that the master key +(or concatenated master 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 master key is compromised, the whole device has +to be erased to prevent further access. Use this option carefully. + +\fB<options>\fR can be [\-\-dump\-master\-key, \-\-key\-file, +\-\-tcrypt\-hidden, \-\-tcrypt\-system, \-\-tcrypt\-backup]. + +The keyfile parameter allows a combination of file content with the +passphrase and can be repeated. +.PP +See also \fBhttps://en.wikipedia.org/wiki/TrueCrypt\fR for more information regarding +TrueCrypt. + +Please note that cryptsetup does not use TrueCrypt code, please report +all problems related to this compatibility extension to the cryptsetup project. +.SH MISCELLANEOUS +.PP +\fIrepair\fR <device> +.IP +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. + +\fBWARNING:\fR Always create a binary backup of the original +header before calling this command. +.PP +\fIbenchmark\fR <options> +.IP +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 \fB\-\-cipher\fR +and \fB\-\-key\-size\fR options or \fB\-\-hash\fR for KDF test. + +\fBNOTE:\fR This benchmark is using 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). + +\fB<options>\fR can be [\-\-cipher, \-\-key\-size, \-\-hash]. +.SH OPTIONS +.TP +.B "\-\-verbose, \-v" +Print more information on command execution. +.TP +.B "\-\-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. +.TP +.B "\-\-type <device-type> +Specifies required device type, for more info +read \fIBASIC COMMANDS\fR section. +.TP +.B "\-\-hash, \-h \fI<hash\-spec>\fR" +Specifies the passphrase hash for \fIopen\fR (for plain and +loopaes device types). + +Specifies the hash used in the LUKS key setup scheme and volume key digest +for \fIluksFormat\fR. The specified hash is used as hash-parameter +for PBKDF2 and for the AF splitter. + +The specified hash name is passed to the compiled-in crypto backend. +Different backends may support different hashes. +For \fIluksFormat\fR, the hash +algorithm must provide at least 160 bits of output, which +excludes, e.g., MD5. Do not use a non-crypto hash like +\fB"crc32"\fR as this breaks security. + +Values compatible with old version of cryptsetup are +\fB"ripemd160"\fR for \fIopen \-\-type plain\fR and +\fB"sha1"\fR for \fIluksFormat\fR. + +Use \fIcryptsetup \-\-help\fR to show the defaults. +.TP +.B "\-\-cipher, \-c \fI<cipher\-spec>\fR" +Set the cipher specification string. + +\fIcryptsetup \-\-help\fR shows the compiled-in defaults. +The current default in the distributed sources is +"aes-cbc-essiv:sha256" for plain dm-crypt and +"aes-xts-plain64" for LUKS. + +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. + +XTS mode requires kernel 2.6.24 or later and plain64 requires +kernel 2.6.33 or later. More information can be found in the FAQ. +.TP +.B "\-\-verify-passphrase, \-y" +When interactively asking for a passphrase, ask for it twice +and complain if both inputs do not match. Advised when creating +a regular mapping for the first time, or when running +\fIluksFormat\fR. Ignored on input from file or stdin. +.TP +.B "\-\-key-file, \-d \fIname\fR" +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. + +With LUKS, passphrases supplied via \-\-key\-file are always +the existing passphrases requested by a command, except in +the case of \fIluksFormat\fR where \-\-key\-file is equivalent +to the positional key file argument. + +If you want to set a new passphrase via key file, you have to +use a positional argument to \fIluksAddKey\fR. + +See section \fBNOTES ON PASSPHRASE PROCESSING\fR for more information. +.TP +.B "\-\-keyfile\-offset \fIvalue\fR" +Skip \fIvalue\fR bytes at the beginning of the key file. +Works with all commands that accept key files. +.TP +.B "\-\-keyfile\-size, \-l \fIvalue\fR" +Read a maximum of \fIvalue\fR 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. +Works with all commands that accept key files. +.TP +.B "\-\-new\-keyfile\-offset \fIvalue\fR" +Skip \fIvalue\fR bytes at the start when +adding a new passphrase from key file with +\fIluksAddKey\fR. +.TP +.B "\-\-new\-keyfile\-size \fIvalue\fR" +Read a maximum of \fIvalue\fR bytes when adding +a new passphrase from key file with \fIluksAddKey\fR. +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. +.TP +.B "\-\-master\-key\-file" +Use a master key stored in a file. + +For \fIluksFormat\fR this +allows creating a LUKS header with this specific +master key. If the master 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 master key was taken from. + +Action \fIluksDump\fR together with \-\-dump\-master\-key +option: The volume (master) key is stored in a file instead of +being printed out to standard output. + +\fBWARNING:\fR If you create your own master key, you +need to make sure to do it right. Otherwise, you can end +up with a low-entropy or otherwise partially predictable +master key which will compromise security. + +For \fIluksAddKey\fR this allows adding a new passphrase +without having to know an existing one. + +For \fIopen\fR this allows one to open the LUKS device +without giving a passphrase. +.TP +.B "\-\-dump\-master\-key" +For \fIluksDump\fR this option includes the master key in the displayed +information. Use with care, as the master key can be used to +bypass the passphrases, see also option \-\-master\-key\-file. +.TP +.B "\-\-json\-file" +Read token json from a file or write token to it. See \fItoken\fR action for more +information. \-\-json\-file=- reads json from standard input or writes it to +standard output respectively. +.TP +.B "\-\-use\-random" +.TP +.B "\-\-use\-urandom" +For \fIluksFormat\fR these options define which kernel random number +generator will be used to create the master key (which is a +long-term key). + +See \fBNOTES ON RANDOM NUMBER GENERATORS\fR for more +information. Use \fIcryptsetup \-\-help\fR +to show the compiled-in default random number generator. + +\fBWARNING:\fR In a low-entropy situation (e.g. in an +embedded system), 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. +.TP +.B "\-\-key\-slot, \-S <0\-7>" +For LUKS operations that add key material, this options allows you +to specify which key slot is selected for the new key. +This option can be used for \fIluksFormat\fR, +and \fIluksAddKey\fR. +.br +In addition, for \fIopen\fR, 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. +.TP +.B "\-\-key\-size, \-s <bits>" +Sets key size in bits. The argument has to be a multiple of +8. The possible key-sizes are limited by the cipher and +mode used. + +See /proc/crypto for more information. Note that key-size +in /proc/crypto is stated in bytes. + +This option can be used for \fIopen \-\-type plain\fR or \fIluksFormat\fR. +All other LUKS actions will use the key-size specified in the LUKS header. +Use \fIcryptsetup \-\-help\fR to show the compiled-in defaults. +.TP +.B "\-\-size, \-b <number of 512 byte sectors>" +Set the size of the device in sectors of 512 bytes. +This option is only relevant for the \fIopen\fR and \fIresize\fR +actions. +.TP +.B "\-\-offset, \-o <number of 512 byte sectors>" +Start offset in the backend device in 512-byte sectors. +This option is only relevant for the \fIopen\fR action with plain +or loopaes device types or for LUKS devices in \fIluksFormat\fR. + +For LUKS, the \-\-offset option sets the data offset (payload) of data +device and must be be aligned to 4096-byte sectors (must be multiple of 8). +This option cannot be combined with \-\-align\-payload option. +.TP +.B "\-\-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 for the \fIopen\fR action with plain +or loopaes device types. + +Hence, if \-\-offset \fIn\fR, and \-\-skip \fIs\fR, sector \fIn\fR +(the first sector of the encrypted device) will get a sector number +of \fIs\fR for the IV calculation. +.TP +.B "\-\-readonly, \-r" +set up a read-only mapping. +.TP +.B "\-\-shared" +Creates an additional mapping for one common +ciphertext device. Arbitrary mappings are supported. +This option is only relevant for the +\fIopen \-\-type plain\fR action. Use \-\-offset, \-\-size and \-\-skip to +specify the mapped area. +.TP +.B "\-\-pbkdf <PBKDF spec>" +Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot. +The PBKDF can be: \fIpbkdf2\fR (for PBKDF2 according to RFC2898), +\fIargon2i\fR for Argon2i or \fIargon2id\fR for Argon2id +(see https://www.cryptolux.org/index.php/Argon2 for more info). + +For LUKS1, only PBKDF2 is accepted (no need to use this option). +The default PBKDF2 for LUKS2 is set during compilation time +and is available in \fIcryptsetup \-\-help\fR 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 (\fI\-\-iter\-time\fR) with required +memory cost \fI\-\-pbkdf\-memory\fR. If it is not possible, +the memory cost is decreased as well. +The parallel cost \fI\-\-pbkdf\-parallel\fR is constant, is is checked +against available CPU cores (if not available, it is decreased) and the maximum +parallel cost is 4. + +You can see all PBKDF parameters for particular LUKS2 keyslot with +\fIluksDump\fR command. + +\fBNOTE:\fR If you do not want to use benchmark and want to specify +all parameters directly, use \fI\-\-pbkdf\-force\-iterations\fR with +\fI\-\-pbkdf\-memory\fR and \fI\-\-pbkdf\-parallel\fR. +This will override the values without benchmarking. +Note it can cause extremely long unlocking time. Use only is specified +cases, for example, if you know that the formatted device will +be used on some small embedded system. +In this case, the LUKS PBKDF2 digest will be set to the minimum iteration count. +.TP +.B "\-\-iter\-time, \-i <number of milliseconds>" +The number of milliseconds to spend with PBKDF passphrase processing. +This option is only relevant for LUKS operations that set or change +passphrases, such as \fIluksFormat\fR or \fIluksAddKey\fR. +Specifying 0 as parameter selects the compiled-in default. +.TP +.B "\-\-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. +.TP +.B "\-\-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. +.TP +.B "\-\-pbkdf\-force\-iterations <num>" +Avoid PBKDF benchmark and set time cost (iterations) directly. +It can be used for LUKS/LUKS2 device only. +See \fI\-\-pbkdf\fR option for more info. +.TP +.B "\-\-batch\-mode, \-q" +Suppresses all confirmation questions. Use with care! + +If the \-y option is not specified, this option also switches off +the passphrase verification for \fIluksFormat\fR. +.TP +.B "\-\-progress-frequency <seconds>" +Print separate line every <seconds> with wipe progress. +.TP +.B "\-\-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, +for example for \fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR. +It has no effect if used in conjunction with \-\-key-file. +.br +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. +.TP +.B "\-\-tries, \-T" +How often the input of the passphrase shall be retried. +This option is relevant +every time a passphrase is asked, for example for +\fIopen\fR, \fIluksFormat\fR or \fIluksAddKey\fR. +The default is 3 tries. +.TP +.B "\-\-align\-payload <number of 512 byte sectors>" +Align payload at a boundary of \fIvalue\fR 512-byte sectors. +This option is relevant for \fIluksFormat\fR. + +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. + +\fBWARNING:\fR 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 \fI\-\-offset\fR option instead. + +.TP +.B "\-\-uuid=\fIUUID\fR" +Use the provided \fIUUID\fR for the \fIluksFormat\fR command +instead of generating a new one. Changes the existing UUID when +used with the \fIluksUUID\fR command. + +The UUID must be provided in the standard UUID format, +e.g. 12345678-1234-1234-1234-123456789abc. +.TP +.B "\-\-allow\-discards\fR" +Allow the use of discard (TRIM) requests for the device. +This option is only relevant for \fIopen\fR action. + +\fBWARNING:\fR 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. +.TP +.B "\-\-perf\-same_cpu_crypt\fR" +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. +This option is only relevant for \fIopen\fR action. + +\fBNOTE:\fR 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. +.TP +.B "\-\-perf\-submit_from_crypt_cpus\fR" +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. +This option is only relevant for \fIopen\fR action. + +\fBNOTE:\fR 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. +.TP +.B "\-\-test\-passphrase\fR" +Do not activate the device, just verify passphrase. +This option is only relevant for \fIopen\fR action (the device +mapping name is not mandatory if this option is used). +.TP +.B "\-\-header\fR <device or file storing the LUKS header>" +Use a detached (separated) metadata device or file where the +LUKS header is stored. This option allows one to store ciphertext +and LUKS header on different devices. + +This option is only relevant for LUKS devices and can be +used with the \fIluksFormat\fR, \fIopen\fR, \fIluksSuspend\fR, +\fIluksResume\fR, \fIstatus\fR and \fIresize\fR commands. + +For \fIluksFormat\fR 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. + +For other commands that change the LUKS header (e.g. \fIluksAddKey\fR), +specify the device or file with the LUKS header directly as the +LUKS device. + +If used with \fIluksFormat\fR, the \-\-align\-payload option is taken +as absolute sector alignment on ciphertext device and can be zero. + +\fBWARNING:\fR 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 for \fIopen\fR +with the \-\-header option. Use with care. +.TP +.B "\-\-header\-backup\-file <file>" +Specify file with header backup for \fIluksHeaderBackup\fR or +\fIluksHeaderBackup\fR actions. +.TP +.B "\-\-force\-password" +Do not use password quality checking for new LUKS passwords. + +This option applies only to \fIluksFormat\fR, \fIluksAddKey\fR and +\fIluksChangeKey\fR and is ignored if cryptsetup is built without +password quality checking support. + +For more info about password quality check, see the manual page +for \fBpwquality.conf(5)\fR and \fBpasswdqc.conf(5)\fR. +.TP +.B "\-\-deferred" +Defers device removal in \fIclose\fR command until the last user closes it. +.TP +.B "\-\-disable\-locks" +Disable lock protection for metadata on disk. +This option is valid only for LUKS2 and ignored for other formats. + +\fBWARNING:\fR 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). +.TP +.B "\-\-disable\-keyring" +Do not load volume key in kernel keyring but use store key directly +in the dm-crypt target. +This option is supported only for the LUKS2 format. +.TP +.B "\-\-key\-description <text>" +Set key description in keyring for use with \fItoken\fR command. +.TP +.B "\-\-priority <normal|prefer|ignore>" +Set a priority for LUKS2 keyslot. +The \fIprefer\fR priority marked slots are tried before \fInormal\fR priority. +The \fIignored\fR priority means, that slot is never used, if not explicitly +requested by \fI\-\-key\-slot\fR option. +.TP +.B "\-\-token\-id" +Specify what token to use in actions \fItoken\fR, \fIopen\fR or \fIresize\fR. +If omitted, all available tokens will be checked before proceeding further with +passphrase prompt. +.TP +.B "\-\-token\-only" +Do not proceed further with action (any of \fItoken\fR, \fIopen\fR or +\fIresize\fR) if token activation failed. Without the option, +action asks for passphrase to proceed further. +.TP +.B "\-\-sector\-size <bytes>" +Set sector size for use with disk encryption. It must be power of two +and in range 512 - 4096 bytes. The default is 512 bytes sectors. +This option is available only in the LUKS2 mode. + +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 \fI\-\-integrity\fR option and dm-integrity journal, +the atomicity of writes is guaranteed in all cases (but it cost write +performance - data has to be written twice). + +Increasing sector size from 512 bytes to 4096 bytes can provide better +performance on most of the modern storage devices and also with some +hw encryption accelerators. +.TP +.B "\-\-persistent" +If used with LUKS2 devices and activation commands like \fIopen\fR, +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.) +Only \fI\-\-allow-discards\fR, \fI\-\-perf\-same_cpu_crypt\fR, +\fI\-\-perf\-submit_from_crypt_cpus\fR and \fI\-\-integrity\-no\-journal\fR +can be stored persistently. +.TP +.B "\-\-refresh" +Refreshes an active device with new set of parameters. See action \fIrefresh\fR description +for more details. +.TP +.B "\-\-label <LABEL>" +.B "\-\-subsystem <SUBSYSTEM>" +Set label and subsystem description for LUKS2 device, can be used +in \fIconfig\fR and \fIformat\fR actions. +The label and subsystem are optional fields and can be later used in udev scripts +for triggering user actions once device marked by these labels is detected. +.TP +.B "\-\-integrity <integrity algorithm>" +Specify integrity algorithm to be used for authenticated disk encryption in LUKS2. + +\fBWARNING: This extension is EXPERIMENTAL\fR 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 \fIAUTHENTICATED DISK ENCRYPTION\fR section. +.TP +.B "\-\-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). +.TP +.B "\-\-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). +.TP +.B "\-\-keyslot\-cipher <cipher\-spec>" +This option can be used to set specific cipher encryption for the LUKS2 keyslot area. +.TP +.B "\-\-keyslot\-key\-size <bits>" +This option can be used to set specific key size for the LUKS2 keyslot area. +.TP +.B "\-\-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. +.TP +.B "\-\-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. + +\fBNOTE:\fR 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. +.TP +.B "\-\-unbound" + +Creates new LUKS2 unbound keyslot. See \fIluksAddKey\fR action for more +details. +.TP +.B "\-\-tcrypt\-hidden" +.B "\-\-tcrypt\-system" +.B "\-\-tcrypt\-backup" +Specify which TrueCrypt on-disk header will be used to open the device. +See \fITCRYPT\fR section for more info. +.TP +.B "\-\-veracrypt" +Allow VeraCrypt compatible mode. Only for TCRYPT extension. +See \fITCRYPT\fR section for more info. +.TP +.B "\-\-veracrypt\-pim" +.B "\-\-veracrypt\-query\-pim" +Use a custom Personal Iteration Multiplier (PIM) for VeraCrypt device. +See \fITCRYPT\fR section for more info. +.TP +.B "\-\-version" +Show the program version. +.TP +.B "\-\-usage" +Show short option help. +.TP +.B "\-\-help, \-?" +Show help text and default parameters. +.SH 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. +.SH NOTES ON 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. + +\fBFrom a terminal\fR: 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. + +\fBFrom stdin\fR: 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. + +\fBFrom a key file\fR: 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. + +\fBWARNING\fR: 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. + + +.SH NOTES ON PASSPHRASE PROCESSING FOR LUKS +LUKS uses PBKDF2 to protect against dictionary attacks +and to give some protection to low-entropy passphrases +(see RFC 2898 and the cryptsetup FAQ). + +\fBFrom a terminal\fR: The passphrase is read until the +first newline and then processed by PBKDF2 without +the newline character. + +\fBFrom stdin\fR: +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. + +\fBFrom key file\fR: +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. + +\fBPassphrase processing\fR: +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. +.SH 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. +.SH NOTES ON 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. +.SH 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. +.SH 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 (master) key. You can switch +between using /dev/random and /dev/urandom here, see +\fP\-\-use\-random\fR and \fP\-\-use\-urandom\fR +options. Using /dev/random on a system without enough entropy sources +can cause \fPluksFormat\fR 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 \fPurandom(4)\fR for more information. +.SH 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 \fIluksOpen\fR +for integrity protected devices. +If you want to format LUKS2 device with data integrity protection, +use \fI\-\-integrity\fR option. + +Some integrity modes requires two independent keys (key for encryption +and for authentication). Both these keys are stored in one LUKS keyslot. + +\fBWARNING:\fR 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. + +.SH 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). +.SH LUKS2 header locking +.PP +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 \fIflock(2)\fR system call. +For a block device, lock is performed over a special file stored +in a locking directory (by default \fI/run/lock/cryptsetup\fR). +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. +.SH DEPRECATED ACTIONS +.PP +The \fIreload\fR action is no longer supported. +Please use \fIdmsetup(8)\fR if you need to +directly manipulate with the device mapping table. +.PP +The \fIluksDelKey\fR was replaced with \fIluksKillSlot\fR. +.PP +.SH REPORTING BUGS +Report bugs, including ones in the documentation, on +the cryptsetup mailing list at <dm-crypt@saout.de> +or in the 'Issues' section on LUKS website. +Please attach the output of the failed command with the +\-\-debug option added. +.SH AUTHORS +cryptsetup originally written by Jana Saout <jana@saout.de> +.br +The LUKS extensions and original man page were written by +Clemens Fruhwirth <clemens@endorphin.org>. +.br +Man page extensions by Milan Broz <gmazyland@gmail.com>. +.br +Man page rewrite and extension by Arno Wagner <arno@wagner.name>. +.SH COPYRIGHT +Copyright \(co 2004 Jana Saout +.br +Copyright \(co 2004-2006 Clemens Fruhwirth +.br +Copyright \(co 2012-2014 Arno Wagner +.br +Copyright \(co 2009-2019 Red Hat, Inc. +.br +Copyright \(co 2009-2019 Milan Broz + +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH SEE ALSO +The LUKS website at \fBhttps://gitlab.com/cryptsetup/cryptsetup/\fR + +The cryptsetup FAQ, contained in the distribution package and +online at +\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions\fR + +The cryptsetup mailing list and list archive, see FAQ entry 1.6. + +The LUKS on-disk format specification available at +\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/Specification\fR diff --git a/man/integritysetup.8 b/man/integritysetup.8 new file mode 100644 index 0000000..5b40b84 --- /dev/null +++ b/man/integritysetup.8 @@ -0,0 +1,221 @@ +.TH INTEGRITYSETUP "8" "January 2019" "integritysetup" "Maintenance Commands" +.SH NAME +integritysetup - manage dm-integrity (block level integrity) volumes +.SH SYNOPSIS +.B integritysetup <options> <action> <action args> +.SH DESCRIPTION +.PP +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 additional data +integrity field per-sector. You can use this additional field directly +with integritysetup utility, or indirectly (for authenticated encryption) +through cryptsetup. + +Integritysetup supports these operations: +.PP +\fIformat\fR <device> +.IP +Formats <device> (calculates space and dm-integrity superblock and wipes the device). + +\fB<options>\fR 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] + +.PP +\fIopen\fR <device> <name> +.br +\fIcreate\fR <name> <device> (\fBOBSOLETE syntax\fR) +.IP +Open a mapping with <name> backed by device <device>. + +\fB<options>\fR 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\-recovery\-mode] + +.PP +\fIclose\fR <name> +.IP +Removes existing mapping <name>. + +For backward compatibility, there is \fBremove\fR command alias +for the \fBclose\fR command. +.PP +\fIstatus\fR <name> +.IP +Reports status for the active integrity mapping <name>. +.PP +\fIdump\fR <device> +.IP +Reports parameters from on-disk stored superblock. + +.SH OPTIONS +.TP +.B "\-\-verbose, \-v" +Print more information on command execution. +.TP +.B "\-\-debug" +Run in debug mode with full diagnostic logs. Debug output +lines are always prefixed by '#'. +.TP +.B "\-\-version" +Show the program version. +.TP +.B "\-\-batch\-mode" +Do not ask for confirmation. +.TP +.B "\-\-progress-frequency <seconds>" +Print separate line every <seconds> with wipe progress. +.TP +.B "\-\-no\-wipe" +Do not wipe the device after format. A device that is not initially wiped will contain invalid checksums. +.TP +.B "\-\-journal\-size, \-j BYTES" +Size of the journal. +.TP +.B "\-\-interleave\-sectors SECTORS" +The number of interleaved sectors. +.TP +.B "\-\-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. +.TP +.B "\-\-journal\-watermark PERCENT" +Journal watermark in percents. When the size of the journal exceeds this watermark, +the journal flush will be started. +.TP +.B "\-\-journal\-commit\-time MS" +Commit time in milliseconds. When this time passes (and no explicit flush operation was issued), +the journal is written. +.TP +.B "\-\-tag\-size, \-t BYTES" +Size of the integrity tag per-sector (here the integrity function will store authentication tag). + +\fBNOTE:\fR The size can be smaller that output size of the hash function, in that case only +part of the hash will be stored. +.TP +.B "\-\-data\-device" +Specify a separate data device that contains existing data. The <device> then will contain +calculated integrity tags and journal for this data device. +.TP +.B "\-\-sector\-size, \-s BYTES" +Sector size (power of two: 512, 1024, 2048, 4096). +.TP +.B "\-\-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. +.TP +.B "\-\-integrity, \-I ALGORITHM" +Use internal integrity calculation (standalone mode). +The integrity algorithm can be CRC (crc32c/crc32) or hash function (sha1, sha256). + +For HMAC (hmac-sha256) you have also to specify an integrity key and its size. +.TP +.B "\-\-integrity\-key\-size BYTES" +The size of the data integrity key. +.TP +.B "\-\-integrity\-key\-file FILE" +The file with the integrity key. +.TP +.B "\-\-integrity\-no\-journal, \-D" +Disable journal for integrity device. + +\fBWARNING:\fR +In case of a crash, it is possible that the data and integrity tag doesn't match +if the journal is disabled. +.TP +.B "\-\-integrity\-recovery\-mode. \-R" +Recovery mode (no journal, no tag checking). +.TP + +\fBNOTE:\fR 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 \fBcryptsetup(8)\fR. +.TP +.B "\-\-journal\-integrity ALGORITHM" +Integrity algorithm for journal area. +See \-\-integrity option for detailed specification. +.TP +.B "\-\-journal\-integrity\-key\-size BYTES" +The size of the journal integrity key. +.TP +.B "\-\-journal\-integrity\-key\-file FILE" +The file with the integrity key. +.TP +.B "\-\-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). +.TP +.B "\-\-journal\-crypt\-key\-size BYTES" +The size of the journal encryption key. +.TP +.B "\-\-journal\-crypt\-key\-file FILE" +The file with the journal encryption key. +.TP +The dm-integrity target is available since Linux kernel version 4.12. +.TP +\fBNOTE:\fR +Format and activation of an integrity device always require superuser +privilege because the superblock is calculated and handled in dm-integrity kernel target. + +.SH 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. + +.SH EXAMPLES +Format the device with default standalone mode (CRC32C): + +.B "integritysetup format <device>" + +Open the device with default parameters: + +.B "integritysetup open <device> test" + +Format the device in standalone mode for use with HMAC(SHA256): + +.B "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: + +.B "integritysetup open <device> test \-\-integrity hmac\-sha256 \ +\-\-integrity\-key\-file <keyfile> \-\-integrity\-key\-size <key_bytes>" + +Dump dm-integrity superblock information: + +.B "integritysetup dump <device>" + +.SH REPORTING BUGS +Report bugs, including ones in the documentation, on +the cryptsetup mailing list at <dm-crypt@saout.de> +or in the 'Issues' section on LUKS website. +Please attach the output of the failed command with the +\-\-debug option added. +.SH AUTHORS +The integritysetup tool is written by Milan Broz <gmazyland@gmail.com> +and is part of the cryptsetup project. +.SH COPYRIGHT +Copyright \(co 2016-2019 Red Hat, Inc. +.br +Copyright \(co 2016-2019 Milan Broz + +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH SEE ALSO +The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR + +The integrity on-disk format specification available at +\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity\fR diff --git a/man/veritysetup.8 b/man/veritysetup.8 new file mode 100644 index 0000000..6878aba --- /dev/null +++ b/man/veritysetup.8 @@ -0,0 +1,228 @@ +.TH VERITYSETUP "8" "January 2019" "veritysetup" "Maintenance Commands" +.SH NAME +veritysetup - manage dm-verity (block level verification) volumes +.SH SYNOPSIS +.B veritysetup <options> <action> <action args> +.SH DESCRIPTION +.PP +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. + +Veritysetup supports these operations: +.PP +\fIformat\fR <data_device> <hash_device> +.IP +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. + +\fB<options>\fR can be [\-\-hash, \-\-no-superblock, \-\-format, +\-\-data-block-size, \-\-hash-block-size, \-\-data-blocks, \-\-hash-offset, +\-\-salt, \-\-uuid] +.PP +\fIopen\fR <data_device> <name> <hash_device> <root_hash> +\fIcreate\fR <name> <data_device> <hash_device> <root_hash> +.IP +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. + +\fB<options>\fR can be [\-\-hash-offset, \-\-no-superblock, +\-\-ignore-corruption or \-\-restart-on-corruption, \-\-ignore-zero-blocks, +\-\-check-at-most-once] + +If option \-\-no-superblock is used, you have to use as the same options +as in initial format operation. +.PP +\fIverify\fR <data_device> <hash_device> <root_hash> +.IP +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. + +\fB<options>\fR can be [\-\-hash-offset, \-\-no-superblock] + +If option \-\-no-superblock is used, you have to use as the same options +as in initial format operation. +.PP +\fIclose\fR <name> +.IP +Removes existing mapping <name>. + +For backward compatibility there is \fBremove\fR command alias +for \fBclose\fR command. +.PP +\fIstatus\fR <name> +.IP +Reports status for the active verity mapping <name>. +.PP +\fIdump\fR <hash_device> +.IP +Reports parameters of verity device from on-disk stored superblock. + +\fB<options>\fR can be [\-\-no-superblock] +.SH OPTIONS +.TP +.B "\-\-verbose, \-v" +Print more information on command execution. +.TP +.B "\-\-debug" +Run in debug mode with full diagnostic logs. Debug output +lines are always prefixed by '#'. +.TP +.B "\-\-no-superblock" +Create or use dm-verity without permanent on-disk superblock. +.TP +.B "\-\-format=number" +Specifies the hash version type. +Format type 0 is original Chrome OS version. Format type 1 is current version. +.TP +.B "\-\-data-block-size=bytes" +Used block size for the data device. +(Note kernel supports only page-size as maximum here.) +.TP +.B "\-\-hash-block-size=bytes" +Used block size for the hash device. +(Note kernel supports only page-size as maximum here.) +.TP +.B "\-\-data-blocks=blocks" +Size of data device used in verification. +If not specified, the whole device is used. +.TP +.B "\-\-hash-offset=bytes" +Offset of hash area/superblock on hash_device. +Value must be aligned to disk sector offset. +.TP +.B "\-\-salt=hex string" +Salt used for format or verification. +Format is a hexadecimal string. +.TP +.B "\-\-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. +.TP +.B "\-\-ignore-corruption", "\-\-restart-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 the kernel is restarted immediately. +(You have to provide way how to avoid restart loops.) + +\fBWARNING:\fR Use these options only for very specific cases. +These options are available since Linux kernel version 4.1. +.TP +.B "\-\-ignore-zero-blocks" +Instruct kernel to not verify blocks that are expected to contain zeroes +and always directly return zeroes instead. + +\fBWARNING:\fR Use this option only in very specific cases. +This option is available since Linux kernel version 4.5. +.TP +.B "\-\-check-at-most-once" +Instruct kernel to verify blocks only the first time they are read +from the data device, rather than every time. + +\fBWARNING:\fR 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. +.TP +.B "\-\-hash=hash" +Hash algorithm for dm-verity. For default see \-\-help option. +.TP +.B "\-\-version" +Show the program version. +.TP +.B "\-\-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. + +Note: block sizes for data and hash devices must match. Also, if the verity data_device is encrypted the fec_device should be too. +.TP +.B "\-\-fec-offset=bytes" +This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding data. +.TP +.B "\-\-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). +.TP +.SH 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. + +.SH EXAMPLES +.B "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). + +.B "veritysetup format <data_device> <hash_device>" + +Calculates and stores verification data on hash_device for the whole data_device. + +.B "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. + +.B "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. + +.B "veritysetup \-\-data-blocks=256 \-\-hash-offset=1052672 verify <data_device> <hash_device> <root_hash>" + +Verifies device without activation (in userspace). + +.B "veritysetup \-\-fec-device=<fec_device> \-\-fec-roots=10 format <data_device> <hash_device>" + +Calculates and stores verification and encoding data for data_device. + +.SH REPORTING BUGS +Report bugs, including ones in the documentation, on +the cryptsetup mailing list at <dm-crypt@saout.de> +or in the 'Issues' section on LUKS website. +Please attach the output of the failed command with the +\-\-debug option added. +.SH AUTHORS +The first implementation of veritysetup was written by Chrome OS authors. + +This version is based on verification code written by Mikulas Patocka <mpatocka@redhat.com> +and rewritten for libcryptsetup by Milan Broz <gmazyland@gmail.com>. +.SH COPYRIGHT +Copyright \(co 2012-2019 Red Hat, Inc. +.br +Copyright \(co 2012-2019 Milan Broz + +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH SEE ALSO +The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR + +The verity on-disk format specification available at +\fBhttps://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity\fR |