man/cryptsetup-reencrypt.8

   1 .TH CRYPTSETUP-REENCRYPT "8" "January 2019" "cryptsetup-reencrypt" "Maintenance Commands"
   2 .SH NAME
   3 cryptsetup-reencrypt - tool for offline LUKS device re-encryption
   4 .SH SYNOPSIS
   5 .B cryptsetup-reencrypt <options> <device>
   6 .SH DESCRIPTION
   7 .PP
   8 Cryptsetup-reencrypt can be used to change reencryption parameters
   9 which otherwise require full on-disk data change (re-encryption).
  10
  11 You can regenerate \fBvolume key\fR (the real key used in on-disk encryption
  12 unclocked by passphrase), \fBcipher\fR, \fBcipher mode\fR.
  13
  14 Cryptsetup-reencrypt reencrypts data on LUKS device in-place. During
  15 reencryption process the LUKS device is marked unavailable.
  16
  17 \fINOTE\fR: If you're looking for LUKS2 online reencryption manual please read cryptsetup(8)
  18 man page instead (see reencrypt action). This page is for legacy offline reencryption
  19 utility only.
  20
  21 \fIWARNING\fR: The cryptsetup-reencrypt program is not resistant to hardware
  22 or kernel failures during reencryption (you can lose your data in this case).
  23
  24 \fIALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL.\fR
  25 .br
  26 The reencryption can be temporarily suspended (by TERM signal or by
  27 using ctrl+c) but you need to retain temporary files named LUKS-<uuid>.[log|org|new].
  28 LUKS device is unavailable until reencryption is finished though.
  29
  30 Current working directory must be writable and temporary
  31 files created during reencryption must be present.
  32
  33 For more info about LUKS see cryptsetup(8).
  34 .PP
  35 .SH OPTIONS
  36 .TP
  37 To start (or continue) re-encryption for <device> use:
  38 .PP
  39 \fIcryptsetup-reencrypt\fR <device>
  40
  41 \fB<options>\fR can be [\-\-batch-mode, \-\-block-size, \-\-cipher | \-\-keep-key,
  42 \-\-debug, \-\-device-size, \-\-hash, \-\-header, \-\-iter-time | \-\-pbkdf\-force\-iterations,
  43 \-\-key-file, \-\-key-size, \-\-key-slot, \-\-keyfile-offset, \-\-keyfile-size,
  44 \-\-master\-key\-file, \-\-tries, \-\-pbkdf, \-\-pbkdf\-memory, \-\-pbkdf\-parallel,
  45 \-\-progress-frequency, \-\-use-directio, \-\-use-random | \-\-use-urandom, \-\-use-fsync,
  46 \-\-uuid, \-\-verbose, \-\-write-log]
  47
  48 To encrypt data on (not yet encrypted) device, use \fI\-\-new\fR in combination
  49 with \fI\-\-reduce-device-size\fR or with \fI\-\-header\fR option for detached header.
  50
  51 To remove encryption from device, use \fI\-\-decrypt\fR.
  52
  53 For detailed description of encryption and key file options see \fIcryptsetup(8)\fR
  54 man page.
  55 .TP
  56 .B "\-\-batch-mode, \-q"
  57 Suppresses all warnings and reencryption progress output.
  58 .TP
  59 .B "\-\-block-size, \-B \fIvalue\fR"
  60 Use re-encryption block size of <value> in MiB.
  61
  62 Values can be between 1 and 64 MiB.
  63 .TP
  64 .B "\-\-cipher, \-c" \fI<cipher-spec>\fR
  65 Set the cipher specification string.
  66 .TP
  67 .B "\-\-debug"
  68 Run in debug mode with full diagnostic logs. Debug output
  69 lines are always prefixed by '#'.
  70 .TP
  71 .B "\-\-decrypt"
  72 Remove encryption (decrypt already encrypted device and remove LUKS header).
  73
  74 \fBWARNING:\fR This is destructive operation and cannot be reverted.
  75 .TP
  76 .B "\-\-device-size \fIsize[units]\fR"
  77 Instead of real device size, use specified value.
  78
  79 It means that only specified area (from the start of the device
  80 to the specified size) will be reencrypted.
  81
  82 If no unit suffix is specified, the size is in bytes.
  83
  84 Unit suffix can be S for 512 byte sectors, K/M/G/T (or KiB,MiB,GiB,TiB)
  85 for units with 1024 base or KB/MB/GB/TB for 1000 base (SI scale).
  86
  87 \fBWARNING:\fR This is destructive operation.
  88 .TP
  89 .B "\-\-hash, \-h \fI<hash-spec>\fR"
  90 Specifies the hash used in the LUKS1 key setup scheme and volume key digest.
  91
  92 \fBNOTE:\fR if this parameter is not specified, default hash algorithm is always used
  93 for new LUKS1 device header.
  94
  95 \fBNOTE:\fR with LUKS2 format this option is only relevant when new keyslot pbkdf algorithm
  96 is set to PBKDF2 (see \fI\-\-pbkdf\fR).
  97 .TP
  98 .B "\-\-header\fR \fI<LUKS header file>\fR"
  99 Use a detached (separated) metadata device or file where the
 100 LUKS header is stored. This option allows one to store ciphertext
 101 and LUKS header on different devices.
 102
 103 \fBWARNING:\fR There is no check whether the ciphertext device specified
 104 actually belongs to the header given.
 105 If used with \fI\-\-new\fR option, the header file will created (or overwritten).
 106 Use with care.
 107 .TP
 108 .B "\-\-iter-time, \-i \fI<milliseconds>\fR"
 109 The number of milliseconds to spend with PBKDF2 passphrase processing for the
 110 new LUKS header.
 111 .TP
 112 .B "\-\-keep-key"
 113 Do not change encryption key, just reencrypt the LUKS header and keyslots.
 114
 115 This option can be combined only with \fI\-\-hash\fR, \fI\-\-iter-time\fR,
 116 \fI\-\-pbkdf\-force\-iterations\fR, \fI\-\-pbkdf\fR (LUKS2 only),
 117 \fI\-\-pbkdf\-memory\fR (Argon2i/id and LUKS2 only) and \fI\-\-pbkdf\-parallel\fR
 118 (Argon2i/id and LUKS2 only) options.
 119 .TP
 120 .B "\-\-key-file, \-d \fIname\fR"
 121 Read the passphrase from file.
 122
 123 \fBWARNING:\fR \-\-key-file option can be used only if there is only one active keyslot,
 124 or alternatively, also if \-\-key-slot option is specified (then all other keyslots
 125 will be disabled in new LUKS device).
 126
 127 If this option is not used, cryptsetup-reencrypt will ask for all active keyslot
 128 passphrases.
 129 .TP
 130 .B "\-\-key-size, \-s \fI<bits>\fR"
 131 Set key size in bits. The argument has to be a multiple of  8.
 132
 133 The possible key-sizes are limited by the cipher and mode used.
 134
 135 If you are increasing key size, there must be enough space in the LUKS header
 136 for enlarged keyslots (data offset must be large enough) or reencryption
 137 cannot be performed.
 138
 139 If there is not enough space for keyslots with new key size,
 140 you can destructively shrink device with \-\-reduce-device-size option.
 141 .TP
 142 .B "\-\-key-slot, \-S <0-MAX>"
 143 Specify which key slot is used. For LUKS1, max keyslot number is 7. For LUKS2, it's 31.
 144
 145 \fBWARNING:\fR All other keyslots will be disabled if this option is used.
 146 .TP
 147 .B "\-\-keyfile-offset \fIvalue\fR"
 148 Skip \fIvalue\fR bytes at the beginning of the key file.
 149 .TP
 150 .B "\-\-keyfile-size, \-l"
 151 Read a maximum of \fIvalue\fR bytes from the key file.
 152 Default is to read the whole file up to the compiled-in
 153 maximum.
 154 .TP
 155 .B "\-\-master\-key\-file"
 156 Use new volume (master) key stored in a file.
 157 .TP
 158 .B "\-\-new, \-N"
 159 Create new header (encrypt not yet encrypted device).
 160
 161 This option must be used together with \-\-reduce-device-size.
 162
 163 \fBWARNING:\fR This is destructive operation and cannot be reverted.
 164 .TP
 165 .B "\-\-pbkdf"
 166 Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS keyslot.
 167 The PBKDF can be: \fIpbkdf2\fR, \fIargon2i\fR for Argon2i or \fIargon2id\fR for Argon2id.
 168
 169 For LUKS1, only \fIpbkdf2\fR is accepted (no need to use this option).
 170 .TP
 171 .B "\-\-pbkdf\-force\-iterations <num>"
 172 Avoid PBKDF benchmark and set time cost (iterations) directly.
 173 .TP
 174 .B "\-\-pbkdf\-memory <number>"
 175 Set the memory cost for PBKDF (for Argon2i/id the number represents kilobytes).
 176 Note that it is maximal value, PBKDF benchmark or available physical memory
 177 can decrease it.
 178 This option is not available for PBKDF2.
 179 .TP
 180 .B "\-\-pbkdf\-parallel <number>"
 181 Set the parallel cost for PBKDF (number of threads, up to 4).
 182 Note that it is maximal value, it is decreased automatically if
 183 CPU online count is lower.
 184 This option is not available for PBKDF2.
 185 .TP
 186 .B "\-\-progress-frequency <seconds>"
 187 Print separate line every <seconds> with reencryption progress.
 188 .TP
 189 .B "\-\-reduce-device-size \fIsize[units]\fR"
 190 Enlarge data offset to specified value by shrinking device size.
 191
 192 This means that last sectors on the original device will be lost,
 193 ciphertext data will be effectively shifted by specified
 194 number of sectors.
 195
 196 It can be useful if you e.g. added some space to underlying
 197 partition (so last sectors contains no data).
 198
 199 For units suffix see \-\-device-size parameter description.
 200
 201 You cannot shrink device more than by 64 MiB (131072 sectors).
 202
 203 \fBWARNING:\fR This is destructive operation and cannot be reverted.
 204 Use with extreme care - shrunk filesystems are usually unrecoverable.
 205 .TP
 206 .B "\-\-tries, \-T"
 207 Number of retries for invalid passphrase entry.
 208 .TP
 209 .B "\-\-type <type>"
 210 Use only while encrypting not yet encrypted device (see \-\-new).
 211
 212 Specify LUKS version when performing in-place encryption. If the parameter
 213 is omitted default value (LUKS1) is used. Type may be one of: \fBluks\fR (default),
 214 \fBluks1\fR or \fBluks2\fR.
 215 .TP
 216 .B "\-\-use-directio"
 217 Use direct-io (O_DIRECT) for all read/write data operations related
 218 to block device undergoing reencryption.
 219
 220 Useful if direct-io operations perform better than normal buffered
 221 operations (e.g. in virtual environments).
 222 .TP
 223 .B "\-\-use-fsync"
 224 Use fsync call after every written block. This applies for reencryption
 225 log files as well.
 226 .TP
 227 .B "\-\-use-random"
 228 .TP
 229 .B "\-\-use-urandom"
 230 Define which kernel random number generator will be used to create the volume key.
 231 .TP
 232 .B "\-\-uuid" \fI<uuid>\fR
 233 Use only while resuming an interrupted decryption process (see \-\-decrypt).
 234
 235 To find out what \fI<uuid>\fR to pass look for temporary files LUKS-<uuid>.[|log|org|new]
 236 of the interrupted decryption process.
 237 .TP
 238 .B "\-\-verbose, \-v"
 239 Print more information on command execution.
 240 .TP
 241 .B "\-\-version"
 242 Show the program version.
 243 .TP
 244 .B "\-\-write-log"
 245 Update log file after every block write. This can slow down reencryption
 246 but will minimize data loss in the case of system crash.
 247
 248 .SH RETURN CODES
 249 Cryptsetup-reencrypt returns 0 on success and a non-zero value on error.
 250
 251 Error codes are: 1 wrong parameters, 2 no permission,
 252 3 out of memory, 4 wrong device specified, 5 device already exists
 253 or device is busy.
 254 .SH EXAMPLES
 255 .TP
 256 Reencrypt /dev/sdb1 (change volume key)
 257 cryptsetup-reencrypt /dev/sdb1
 258 .TP
 259 Reencrypt and also change cipher and cipher mode
 260 cryptsetup-reencrypt /dev/sdb1 \-c aes-xts-plain64
 261 .TP
 262 Add LUKS encryption to not yet encrypted device
 263
 264 First, be sure you have space added to disk.
 265
 266 Or alternatively shrink filesystem in advance.
 267 .br
 268 Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
 269
 270 fdisk \-u /dev/sdb # move sdb1 partition end + 4096 sectors
 271 (or use resize2fs or tool for your filesystem and shrink it)
 272
 273 cryptsetup-reencrypt /dev/sdb1 \-\-new \-\-reduce-device-size 4096S
 274 .TP
 275 Remove LUKS encryption completely
 276
 277 cryptsetup-reencrypt /dev/sdb1 \-\-decrypt
 278
 279 .SH REPORTING BUGS
 280 Report bugs, including ones in the documentation, on
 281 the cryptsetup mailing list at <dm-crypt@saout.de>
 282 or in the 'Issues' section on LUKS website.
 283 Please attach the output of the failed command with the
 284 \-\-debug option added.
 285 .SH AUTHORS
 286 Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
 287 .SH COPYRIGHT
 288 Copyright \(co 2012-2020 Milan Broz
 289 .br
 290 Copyright \(co 2012-2020 Red Hat, Inc.
 291
 292 This is free software; see the source for copying conditions.  There is NO
 293 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 294 .SH SEE ALSO
 295 The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR