man/cryptsetup-reencrypt.8 - manifest_repos/cryptsetup - Git at Google

 .TH CRYPTSETUP-REENCRYPT "8" "March 2017" "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 you 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 by 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, \-\-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,
 \-\-uuid]

 To encrypt data on (not yet encrypted) device, use \fI\-\-new\fR with combination
 with \fI\-\-reduce-device-size\fR.

 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.
 .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.
 .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 "\-\-hash, \-h \fI<hash-spec>\fR"
 Specifies the hash used in the LUKS 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.
 .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.
 .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,
 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.

 \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 "\-\-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.
 .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.

 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 "\-\-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.

 \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.
 .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 "\-\-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 "\-\-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.
 .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 "\-\-batch-mode, \-q"
 Suppresses all warnings and reencryption progress output.
 .TP
 .B "\-\-version"
 Show the program version.
 .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-2017 Milan Broz
 .br
 Copyright \(co 2012-2017 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
	.TH CRYPTSETUP-REENCRYPT "8" "March 2017" "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 you 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 by 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, \-\-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,
	\-\-uuid]

	To encrypt data on (not yet encrypted) device, use \fI\-\-new\fR with combination
	with \fI\-\-reduce-device-size\fR.

	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.
	.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.
	.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 "\-\-hash, \-h \fI<hash-spec>\fR"
	Specifies the hash used in the LUKS 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.
	.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.
	.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,
	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.

	\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 "\-\-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.
	.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.

	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 "\-\-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.

	\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.
	.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 "\-\-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 "\-\-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.
	.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 "\-\-batch-mode, \-q"
	Suppresses all warnings and reencryption progress output.
	.TP
	.B "\-\-version"
	Show the program version.
	.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-2017 Milan Broz
	.br
	Copyright \(co 2012-2017 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