-.TH CRYPTSETUP-REENCRYPT "8" "June 2012" "cryptsetup-reencrypt" "Maintenance Commands"
+.TH CRYPTSETUP-REENCRYPT "8" "January 2021" "cryptsetup-reencrypt" "Maintenance Commands"
.SH NAME
cryptsetup-reencrypt - tool for offline LUKS device re-encryption
.SH SYNOPSIS
Cryptsetup-reencrypt reencrypts data on LUKS device in-place. During
reencryption process the LUKS device is marked unavailable.
+\fINOTE\fR: If you're looking for LUKS2 online reencryption manual please read cryptsetup(8)
+man page instead (see reencrypt action). This page is for legacy offline reencryption
+utility only.
+
\fIWARNING\fR: The cryptsetup-reencrypt program is not resistant to hardware
-or kernel failures during reencryption (you can lose you data in this case).
+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
-\fITHIS TOOL IS EXPERIMENTAL.\fR
-
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 by writable and temporary
+Current working directory must be writable and temporary
files created during reencryption must be present.
For more info about LUKS see cryptsetup(8).
.PP
\fIcryptsetup-reencrypt\fR <device>
-\fB<options>\fR can be [\-\-block-size, \-\-cipher, \-\-hash, \-\-iter-time,
-\-\-use-random | \-\-use-urandom, \-\-key-file, \-\-key-slot, \-\-keyfile-offset,
-\-\-keyfile-size, \-\-tries, \-\-use-directio, \-\-use-fsync, \-\-write-log]
+\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 in 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 "\-\-verbose, \-v"
-Print more information on command execution.
+.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 "\-\-cipher, \-c" \fI<cipher-spec>\fR
-Set the cipher specification string.
+.B "\-\-decrypt"
+Remove encryption (decrypt already encrypted device and remove LUKS header).
+
+\fBWARNING:\fR This is destructive operation and cannot be reverted.
.TP
-.B "\-\-key-size, \-s \fI<bits>\fR"
-Set key size in bits. The argument has to be a multiple of 8.
+.B "\-\-device-size \fIsize[units]\fR"
+Instead of real device size, use specified value.
-The possible key-sizes are limited by the cipher and mode used.
+It means that only specified area (from the start of the device
+to the specified size) will be reencrypted.
-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 no unit suffix is specified, the size is in bytes.
-If there is not enough space for keyslots with new key size,
-you can destructively shrink device with \-\-reduce-device-size option.
+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 LUKS key setup scheme and volume key digest.
+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 "\-\-use-random"
-.TP
-.B "\-\-use-urandom"
-Define which kernel random number generator will be used to create the volume key.
+.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.
-WARNING: \-\-key-file option can be used only if there only one active keyslot,
+\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-slot, \-S <0-7>"
-Specify which key slot is used.
+.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.
-WARNING: All other keyslots will be disabled if this option is used.
+\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.
Default is to read the whole file up to the compiled-in
maximum.
.TP
-.B "\-\-tries, \-T"
-Number of retries for invalid passphrase entry.
+.B "\-\-master\-key\-file"
+Use new volume (master) key stored in a file.
.TP
-.B "\-\-block-size, \-B \fIvalue\fR"
-Use re-encryption block size of <value> in MiB.
+.B "\-\-new, \-N"
+Create new header (encrypt not yet encrypted device).
-Values can be between 1 and 64 MiB.
+This option must be used together with \-\-reduce-device-size.
+
+\fBWARNING:\fR This is destructive operation and cannot be reverted.
.TP
-.B "\-\-reduce-device-size \fInumber of 512 bytes sectors\fR"
-Enlarge data offset for specified value of sectors by shrinking
-device size.
+.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 usefull if you e.g. added some space to underlying
+It can be useful if you e.g. added some space to underlying
partition (so last sectors contains no data).
-WARNING: This is destructive operation and cannot be reverted.
-Use with extreme care - shrinked filesystems are usually unrecoverable.
+For units suffix see \-\-device-size parameter description.
You cannot shrink device more than by 64 MiB (131072 sectors).
-.TP
-.B "\-\-new, N"
-Create new header (encrypt not yet encrypted device).
-This option must be used together with \-\-reduce-device-size.
-
-WARNING: This is destructive operation and cannot be reverted.
+\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.
+Use direct-io (O_DIRECT) for all read/write data operations related
+to block device undergoing reencryption.
-Usefull if direct-io operations perform better than normal buffered
+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.
+Use fsync call after every written block. This applies for reencryption
+log files as well.
.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.
+.B "\-\-use-random"
.TP
-.B "\-\-batch-mode, \-q"
-Suppresses all warnings and reencryption progress output.
+.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.
cryptsetup-reencrypt /dev/sdb1
.TP
Reencrypt and also change cipher and cipher mode
-cryptsetup-reencrypt /dev/sdb1 -c aes-xts-plain64
+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
+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 --new --reduce-device-size 4096
+cryptsetup-reencrypt /dev/sdb1 \-\-decrypt
.SH REPORTING BUGS
Report bugs, including ones in the documentation, on
.SH AUTHORS
Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
.SH COPYRIGHT
-Copyright \(co 2012 Milan Broz
+Copyright \(co 2012-2021 Milan Broz
.br
-Copyright \(co 2012 Red Hat, Inc.
+Copyright \(co 2012-2021 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 \fBhttp://code.google.com/p/cryptsetup/\fR
+The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR
projects / platform / upstream / cryptsetup.git / blobdiff