-.TH CRYPTSETUP-REENCRYPT "8" "January 2015" "cryptsetup-reencrypt" "Maintenance Commands"
+.TH CRYPTSETUP-REENCRYPT "8" "January 2019" "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 [\-\-batch-mode, \-\-block-size, \-\-cipher, \-\-debug,
-\-\-device-size, \-\-hash, \-\-iter-time, \-\-use-random | \-\-use-urandom,
-\-\-keep-key, \-\-key-size, \-\-key-file, \-\-key-slot, \-\-keyfile-offset,
-\-\-keyfile-size, \-\-tries, \-\-use-directio, \-\-use-fsync, \-\-verbose, \-\-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 with combination
-with \fI\-\-reduce-device-size\fR.
+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 device header.
+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.
-\fBWARNING:\fR \-\-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.
\fBWARNING:\fR All other keyslots will be disabled if this option is used.
.TP
Default is to read the whole file up to the compiled-in
maximum.
.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 or \fI\-\-iter-time\fR
-options.
-.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.
-
-Values can be between 1 and 64 MiB.
-.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.
-
-\fBWARNING:\fR This is destructive operation.
+.B "\-\-new, \-N"
+Create new header (encrypt not yet encrypted device).
-If no unit suffix is specified, the size is in bytes.
+This option must be used together with \-\-reduce-device-size.
-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 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.
-\fBWARNING:\fR This is destructive operation.
+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.
For units suffix see \-\-device-size parameter description.
-\fBWARNING:\fR This is destructive operation and cannot be reverted.
-Use with extreme care - shrinked filesystems are usually unrecoverable.
-
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.
\fBWARNING:\fR This is destructive operation and cannot be reverted.
+Use with extreme care - shrunk filesystems are usually unrecoverable.
.TP
-.B "\-\-decrypt"
-Remove encryption (decrypt already encrypted device and remove LUKS header).
+.B "\-\-tries, \-T"
+Number of retries for invalid passphrase entry.
+.TP
+.B "\-\-type <type>"
+Use only while encrypting not yet encrypted device (see \-\-new).
-\fBWARNING:\fR This is destructive operation and cannot be reverted.
+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
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.
.SH AUTHORS
Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
.SH COPYRIGHT
-Copyright \(co 2012-2015 Milan Broz
+Copyright \(co 2012-2020 Milan Broz
.br
-Copyright \(co 2012-2013 Red Hat, Inc.
+Copyright \(co 2012-2020 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.
projects / platform / upstream / cryptsetup.git / blobdiff