|
Packit |
94f725 |
.TH CRYPTSETUP-REENCRYPT "8" "January 2019" "cryptsetup-reencrypt" "Maintenance Commands"
|
|
Packit |
94f725 |
.SH NAME
|
|
Packit |
94f725 |
cryptsetup-reencrypt - tool for offline LUKS device re-encryption
|
|
Packit |
94f725 |
.SH SYNOPSIS
|
|
Packit |
94f725 |
.B cryptsetup-reencrypt <options> <device>
|
|
Packit |
94f725 |
.SH DESCRIPTION
|
|
Packit |
94f725 |
.PP
|
|
Packit |
94f725 |
Cryptsetup-reencrypt can be used to change reencryption parameters
|
|
Packit |
94f725 |
which otherwise require full on-disk data change (re-encryption).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
You can regenerate \fBvolume key\fR (the real key used in on-disk encryption
|
|
Packit |
94f725 |
unclocked by passphrase), \fBcipher\fR, \fBcipher mode\fR.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
Cryptsetup-reencrypt reencrypts data on LUKS device in-place. During
|
|
Packit |
94f725 |
reencryption process the LUKS device is marked unavailable.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fINOTE\fR: If you're looking for LUKS2 online reencryption manual please read cryptsetup(8)
|
|
Packit |
94f725 |
man page instead (see reencrypt action). This page is for legacy offline reencryption
|
|
Packit |
94f725 |
utility only.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fIWARNING\fR: The cryptsetup-reencrypt program is not resistant to hardware
|
|
Packit |
94f725 |
or kernel failures during reencryption (you can lose your data in this case).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fIALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL.\fR
|
|
Packit |
94f725 |
.br
|
|
Packit |
94f725 |
The reencryption can be temporarily suspended (by TERM signal or by
|
|
Packit |
94f725 |
using ctrl+c) but you need to retain temporary files named LUKS-<uuid>.[log|org|new].
|
|
Packit |
94f725 |
LUKS device is unavailable until reencryption is finished though.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
Current working directory must be writable and temporary
|
|
Packit |
94f725 |
files created during reencryption must be present.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
For more info about LUKS see cryptsetup(8).
|
|
Packit |
94f725 |
.PP
|
|
Packit |
94f725 |
.SH OPTIONS
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
To start (or continue) re-encryption for <device> use:
|
|
Packit |
94f725 |
.PP
|
|
Packit |
94f725 |
\fIcryptsetup-reencrypt\fR <device>
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fB<options>\fR can be [\-\-batch-mode, \-\-block-size, \-\-cipher | \-\-keep-key,
|
|
Packit |
94f725 |
\-\-debug, \-\-device-size, \-\-hash, \-\-header, \-\-iter-time | \-\-pbkdf\-force\-iterations,
|
|
Packit |
94f725 |
\-\-key-file, \-\-key-size, \-\-key-slot, \-\-keyfile-offset, \-\-keyfile-size,
|
|
Packit |
94f725 |
\-\-master\-key\-file, \-\-tries, \-\-pbkdf, \-\-pbkdf\-memory, \-\-pbkdf\-parallel,
|
|
Packit |
94f725 |
\-\-progress-frequency, \-\-use-directio, \-\-use-random | \-\-use-urandom, \-\-use-fsync,
|
|
Packit |
94f725 |
\-\-uuid, \-\-verbose, \-\-write-log]
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
To encrypt data on (not yet encrypted) device, use \fI\-\-new\fR in combination
|
|
Packit |
94f725 |
with \fI\-\-reduce-device-size\fR or with \fI\-\-header\fR option for detached header.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
To remove encryption from device, use \fI\-\-decrypt\fR.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
For detailed description of encryption and key file options see \fIcryptsetup(8)\fR
|
|
Packit |
94f725 |
man page.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-batch-mode, \-q"
|
|
Packit |
94f725 |
Suppresses all warnings and reencryption progress output.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-block-size, \-B \fIvalue\fR"
|
|
Packit |
94f725 |
Use re-encryption block size of <value> in MiB.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
Values can be between 1 and 64 MiB.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-cipher, \-c" \fI<cipher-spec>\fR
|
|
Packit |
94f725 |
Set the cipher specification string.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-debug"
|
|
Packit |
94f725 |
Run in debug mode with full diagnostic logs. Debug output
|
|
Packit |
94f725 |
lines are always prefixed by '#'.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-decrypt"
|
|
Packit |
94f725 |
Remove encryption (decrypt already encrypted device and remove LUKS header).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fBWARNING:\fR This is destructive operation and cannot be reverted.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-device-size \fIsize[units]\fR"
|
|
Packit |
94f725 |
Instead of real device size, use specified value.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
It means that only specified area (from the start of the device
|
|
Packit |
94f725 |
to the specified size) will be reencrypted.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
If no unit suffix is specified, the size is in bytes.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
Unit suffix can be S for 512 byte sectors, K/M/G/T (or KiB,MiB,GiB,TiB)
|
|
Packit |
94f725 |
for units with 1024 base or KB/MB/GB/TB for 1000 base (SI scale).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fBWARNING:\fR This is destructive operation.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-hash, \-h \fI<hash-spec>\fR"
|
|
Packit |
94f725 |
Specifies the hash used in the LUKS1 key setup scheme and volume key digest.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fBNOTE:\fR if this parameter is not specified, default hash algorithm is always used
|
|
Packit |
94f725 |
for new LUKS1 device header.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fBNOTE:\fR with LUKS2 format this option is only relevant when new keyslot pbkdf algorithm
|
|
Packit |
94f725 |
is set to PBKDF2 (see \fI\-\-pbkdf\fR).
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-header\fR \fI<LUKS header file>\fR"
|
|
Packit |
94f725 |
Use a detached (separated) metadata device or file where the
|
|
Packit |
94f725 |
LUKS header is stored. This option allows one to store ciphertext
|
|
Packit |
94f725 |
and LUKS header on different devices.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fBWARNING:\fR There is no check whether the ciphertext device specified
|
|
Packit |
94f725 |
actually belongs to the header given.
|
|
Packit |
94f725 |
If used with \fI\-\-new\fR option, the header file will created (or overwritten).
|
|
Packit |
94f725 |
Use with care.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-iter-time, \-i \fI<milliseconds>\fR"
|
|
Packit |
94f725 |
The number of milliseconds to spend with PBKDF2 passphrase processing for the
|
|
Packit |
94f725 |
new LUKS header.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-keep-key"
|
|
Packit |
94f725 |
Do not change encryption key, just reencrypt the LUKS header and keyslots.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
This option can be combined only with \fI\-\-hash\fR, \fI\-\-iter-time\fR,
|
|
Packit |
94f725 |
\fI\-\-pbkdf\-force\-iterations\fR, \fI\-\-pbkdf\fR (LUKS2 only),
|
|
Packit |
94f725 |
\fI\-\-pbkdf\-memory\fR (Argon2i/id and LUKS2 only) and \fI\-\-pbkdf\-parallel\fR
|
|
Packit |
94f725 |
(Argon2i/id and LUKS2 only) options.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-key-file, \-d \fIname\fR"
|
|
Packit |
94f725 |
Read the passphrase from file.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fBWARNING:\fR \-\-key-file option can be used only if there is only one active keyslot,
|
|
Packit |
94f725 |
or alternatively, also if \-\-key-slot option is specified (then all other keyslots
|
|
Packit |
94f725 |
will be disabled in new LUKS device).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
If this option is not used, cryptsetup-reencrypt will ask for all active keyslot
|
|
Packit |
94f725 |
passphrases.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-key-size, \-s \fI<bits>\fR"
|
|
Packit |
94f725 |
Set key size in bits. The argument has to be a multiple of 8.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
The possible key-sizes are limited by the cipher and mode used.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
If you are increasing key size, there must be enough space in the LUKS header
|
|
Packit |
94f725 |
for enlarged keyslots (data offset must be large enough) or reencryption
|
|
Packit |
94f725 |
cannot be performed.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
If there is not enough space for keyslots with new key size,
|
|
Packit |
94f725 |
you can destructively shrink device with \-\-reduce-device-size option.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-key-slot, \-S <0-MAX>"
|
|
Packit |
94f725 |
Specify which key slot is used. For LUKS1, max keyslot number is 7. For LUKS2, it's 31.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fBWARNING:\fR All other keyslots will be disabled if this option is used.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-keyfile-offset \fIvalue\fR"
|
|
Packit |
94f725 |
Skip \fIvalue\fR bytes at the beginning of the key file.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-keyfile-size, \-l"
|
|
Packit |
94f725 |
Read a maximum of \fIvalue\fR bytes from the key file.
|
|
Packit |
94f725 |
Default is to read the whole file up to the compiled-in
|
|
Packit |
94f725 |
maximum.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-master\-key\-file"
|
|
Packit |
94f725 |
Use new volume (master) key stored in a file.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-new, \-N"
|
|
Packit |
94f725 |
Create new header (encrypt not yet encrypted device).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
This option must be used together with \-\-reduce-device-size.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fBWARNING:\fR This is destructive operation and cannot be reverted.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-pbkdf"
|
|
Packit |
94f725 |
Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot.
|
|
Packit |
94f725 |
The PBKDF can be: \fIpbkdf2\fR, \fIargon2i\fR for Argon2i or \fIargon2id\fR for Argon2id.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
For LUKS1, only \fIpbkdf2\fR is accepted (no need to use this option).
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-pbkdf\-force\-iterations <num>"
|
|
Packit |
94f725 |
Avoid PBKDF benchmark and set time cost (iterations) directly.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-pbkdf\-memory <number>"
|
|
Packit |
94f725 |
Set the memory cost for PBKDF (for Argon2i/id the number represents kilobytes).
|
|
Packit |
94f725 |
Note that it is maximal value, PBKDF benchmark or available physical memory
|
|
Packit |
94f725 |
can decrease it.
|
|
Packit |
94f725 |
This option is not available for PBKDF2.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-pbkdf\-parallel <number>"
|
|
Packit |
94f725 |
Set the parallel cost for PBKDF (number of threads, up to 4).
|
|
Packit |
94f725 |
Note that it is maximal value, it is decreased automatically if
|
|
Packit |
94f725 |
CPU online count is lower.
|
|
Packit |
94f725 |
This option is not available for PBKDF2.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-progress-frequency <seconds>"
|
|
Packit |
94f725 |
Print separate line every <seconds> with reencryption progress.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-reduce-device-size \fIsize[units]\fR"
|
|
Packit |
94f725 |
Enlarge data offset to specified value by shrinking device size.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
This means that last sectors on the original device will be lost,
|
|
Packit |
94f725 |
ciphertext data will be effectively shifted by specified
|
|
Packit |
94f725 |
number of sectors.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
It can be useful if you e.g. added some space to underlying
|
|
Packit |
94f725 |
partition (so last sectors contains no data).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
For units suffix see \-\-device-size parameter description.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
You cannot shrink device more than by 64 MiB (131072 sectors).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
\fBWARNING:\fR This is destructive operation and cannot be reverted.
|
|
Packit |
94f725 |
Use with extreme care - shrunk filesystems are usually unrecoverable.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-tries, \-T"
|
|
Packit |
94f725 |
Number of retries for invalid passphrase entry.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-type <type>"
|
|
Packit |
94f725 |
Use only while encrypting not yet encrypted device (see \-\-new).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
Specify LUKS version when performing in-place encryption. If the parameter
|
|
Packit |
94f725 |
is omitted default value (LUKS1) is used. Type may be one of: \fBluks\fR (default),
|
|
Packit |
94f725 |
\fBluks1\fR or \fBluks2\fR.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-use-directio"
|
|
Packit |
94f725 |
Use direct-io (O_DIRECT) for all read/write data operations related
|
|
Packit |
94f725 |
to block device undergoing reencryption.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
Useful if direct-io operations perform better than normal buffered
|
|
Packit |
94f725 |
operations (e.g. in virtual environments).
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-use-fsync"
|
|
Packit |
94f725 |
Use fsync call after every written block. This applies for reencryption
|
|
Packit |
94f725 |
log files as well.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-use-random"
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-use-urandom"
|
|
Packit |
94f725 |
Define which kernel random number generator will be used to create the volume key.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-uuid" \fI<uuid>\fR
|
|
Packit |
94f725 |
Use only while resuming an interrupted decryption process (see \-\-decrypt).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
To find out what \fI<uuid>\fR to pass look for temporary files LUKS-<uuid>.[|log|org|new]
|
|
Packit |
94f725 |
of the interrupted decryption process.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-verbose, \-v"
|
|
Packit |
94f725 |
Print more information on command execution.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-version"
|
|
Packit |
94f725 |
Show the program version.
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
.B "\-\-write-log"
|
|
Packit |
94f725 |
Update log file after every block write. This can slow down reencryption
|
|
Packit |
94f725 |
but will minimize data loss in the case of system crash.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
.SH RETURN CODES
|
|
Packit |
94f725 |
Cryptsetup-reencrypt returns 0 on success and a non-zero value on error.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
Error codes are: 1 wrong parameters, 2 no permission,
|
|
Packit |
94f725 |
3 out of memory, 4 wrong device specified, 5 device already exists
|
|
Packit |
94f725 |
or device is busy.
|
|
Packit |
94f725 |
.SH EXAMPLES
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
Reencrypt /dev/sdb1 (change volume key)
|
|
Packit |
94f725 |
cryptsetup-reencrypt /dev/sdb1
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
Reencrypt and also change cipher and cipher mode
|
|
Packit |
94f725 |
cryptsetup-reencrypt /dev/sdb1 \-c aes-xts-plain64
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
Add LUKS encryption to not yet encrypted device
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
First, be sure you have space added to disk.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
Or alternatively shrink filesystem in advance.
|
|
Packit |
94f725 |
.br
|
|
Packit |
94f725 |
Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
fdisk \-u /dev/sdb # move sdb1 partition end + 4096 sectors
|
|
Packit |
94f725 |
(or use resize2fs or tool for your filesystem and shrink it)
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
cryptsetup-reencrypt /dev/sdb1 \-\-new \-\-reduce-device-size 4096S
|
|
Packit |
94f725 |
.TP
|
|
Packit |
94f725 |
Remove LUKS encryption completely
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
cryptsetup-reencrypt /dev/sdb1 \-\-decrypt
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
.SH REPORTING BUGS
|
|
Packit |
94f725 |
Report bugs, including ones in the documentation, on
|
|
Packit |
94f725 |
the cryptsetup mailing list at <dm-crypt@saout.de>
|
|
Packit |
94f725 |
or in the 'Issues' section on LUKS website.
|
|
Packit |
94f725 |
Please attach the output of the failed command with the
|
|
Packit |
94f725 |
\-\-debug option added.
|
|
Packit |
94f725 |
.SH AUTHORS
|
|
Packit |
94f725 |
Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
|
|
Packit |
94f725 |
.SH COPYRIGHT
|
|
Packit |
94f725 |
Copyright \(co 2012-2020 Milan Broz
|
|
Packit |
94f725 |
.br
|
|
Packit |
94f725 |
Copyright \(co 2012-2020 Red Hat, Inc.
|
|
Packit |
94f725 |
|
|
Packit |
94f725 |
This is free software; see the source for copying conditions. There is NO
|
|
Packit |
94f725 |
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
Packit |
94f725 |
.SH SEE ALSO
|
|
Packit |
94f725 |
The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR
|