man/cryptsetup-reencrypt.8

   1 .TH CRYPTSETUP-REENCRYPT "8" "January 2015" "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 \fIWARNING\fR: The cryptsetup-reencrypt program is not resistant to hardware
  18 or kernel failures during reencryption (you can lose you data in this case).
  19
  20 \fIALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL.\fR
  21 .br
  22 \fITHIS TOOL IS EXPERIMENTAL.\fR
  23
  24 The reencryption can be temporarily suspended (by TERM signal or by
  25 using ctrl+c) but you need to retain temporary files named LUKS-<uuid>.[log|org|new].
  26 LUKS device is unavailable until reencryption is finished though.
  27
  28 Current working directory must by writable and temporary
  29 files created during reencryption must be present.
  30
  31 For more info about LUKS see cryptsetup(8).
  32 .PP
  33 .SH OPTIONS
  34 .TP
  35 To start (or continue) re-encryption for <device> use:
  36 .PP
  37 \fIcryptsetup-reencrypt\fR <device>
  38
  39 \fB<options>\fR can be [\-\-batch-mode, \-\-block-size, \-\-cipher, \-\-debug,
  40 \-\-device-size, \-\-hash, \-\-iter-time, \-\-use-random | \-\-use-urandom,
  41 \-\-keep-key, \-\-key-size, \-\-key-file, \-\-key-slot, \-\-keyfile-offset,
  42 \-\-keyfile-size, \-\-tries, \-\-use-directio, \-\-use-fsync, \-\-verbose, \-\-write-log]
  43
  44 To encrypt data on (not yet encrypted) device, use \fI\-\-new\fR with combination
  45 with \fI\-\-reduce-device-size\fR.
  46
  47 To remove encryption from device, use \fI\-\-decrypt\fR.
  48
  49 For detailed description of encryption and key file options see \fIcryptsetup(8)\fR
  50 man page.
  51 .TP
  52 .B "\-\-verbose, \-v"
  53 Print more information on command execution.
  54 .TP
  55 .B "\-\-debug"
  56 Run in debug mode with full diagnostic logs. Debug output
  57 lines are always prefixed by '#'.
  58 .TP
  59 .B "\-\-cipher, \-c" \fI<cipher-spec>\fR
  60 Set the cipher specification string.
  61 .TP
  62 .B "\-\-key-size, \-s \fI<bits>\fR"
  63 Set key size in bits. The argument has to be a multiple of  8.
  64
  65 The possible key-sizes are limited by the cipher and mode used.
  66
  67 If you are increasing key size, there must be enough space in the LUKS header
  68 for enlarged keyslots (data offset must be large enough) or reencryption
  69 cannot be performed.
  70
  71 If there is not enough space for keyslots with new key size,
  72 you can destructively shrink device with \-\-reduce-device-size option.
  73 .TP
  74 .B "\-\-hash, \-h \fI<hash-spec>\fR"
  75 Specifies the hash used in the LUKS key setup scheme and volume key digest.
  76
  77 \fBNOTE:\fR if this parameter is not specified, default hash algorithm is always used
  78 for new device header.
  79 .TP
  80 .B "\-\-iter-time, \-i \fI<milliseconds>\fR"
  81 The number of milliseconds to spend with PBKDF2 passphrase processing for the
  82 new LUKS header.
  83 .TP
  84 .B "\-\-use-random"
  85 .TP
  86 .B "\-\-use-urandom"
  87 Define which kernel random number generator will be used to create the volume key.
  88 .TP
  89 .B "\-\-key-file, \-d \fIname\fR"
  90 Read the passphrase from file.
  91
  92 \fBWARNING:\fR \-\-key-file option can be used only if there only one active keyslot,
  93 or alternatively, also if \-\-key-slot option is specified (then all other keyslots
  94 will be disabled in new LUKS device).
  95
  96 If this option is not used, cryptsetup-reencrypt will ask for all active keyslot
  97 passphrases.
  98 .TP
  99 .B "\-\-key-slot, \-S <0-7>"
 100 Specify which key slot is used.
 101
 102 \fBWARNING:\fR All other keyslots will be disabled if this option is used.
 103 .TP
 104 .B "\-\-keyfile-offset \fIvalue\fR"
 105 Skip \fIvalue\fR bytes at the beginning of the key file.
 106 .TP
 107 .B "\-\-keyfile-size, \-l"
 108 Read a maximum of \fIvalue\fR bytes from the key file.
 109 Default is to read the whole file up to the compiled-in
 110 maximum.
 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 or \fI\-\-iter-time\fR
 116 options.
 117 .TP
 118 .B "\-\-tries, \-T"
 119 Number of retries for invalid passphrase entry.
 120 .TP
 121 .B "\-\-block-size, \-B \fIvalue\fR"
 122 Use re-encryption block size of <value> in MiB.
 123
 124 Values can be between 1 and 64 MiB.
 125 .TP
 126 .B "\-\-device-size \fIsize[units]\fR"
 127 Instead of real device size, use specified value.
 128
 129 It means that only specified area (from the start of the device
 130 to the specified size) will be reencrypted.
 131
 132 \fBWARNING:\fR This is destructive operation.
 133
 134 If no unit suffix is specified, the size is in bytes.
 135
 136 Unit suffix can be S for 512 byte sectors, K/M/G/T (or KiB,MiB,GiB,TiB)
 137 for units with 1024 base or KB/MB/GB/TB for 1000 base (SI scale).
 138
 139 \fBWARNING:\fR This is destructive operation.
 140 .TP
 141 .B "\-\-reduce-device-size \fIsize[units]\fR"
 142 Enlarge data offset to specified value by shrinking device size.
 143
 144 This means that last sectors on the original device will be lost,
 145 ciphertext data will be effectively shifted by specified
 146 number of sectors.
 147
 148 It can be useful if you e.g. added some space to underlying
 149 partition (so last sectors contains no data).
 150
 151 For units suffix see \-\-device-size parameter description.
 152
 153 \fBWARNING:\fR This is destructive operation and cannot be reverted.
 154 Use with extreme care - shrinked filesystems are usually unrecoverable.
 155
 156 You cannot shrink device more than by 64 MiB (131072 sectors).
 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 "\-\-decrypt"
 166 Remove encryption (decrypt already encrypted device and remove LUKS header).
 167
 168 \fBWARNING:\fR This is destructive operation and cannot be reverted.
 169 .TP
 170 .B "\-\-use-directio"
 171 Use direct-io (O_DIRECT) for all read/write data operations related
 172 to block device undergoing reencryption.
 173
 174 Useful if direct-io operations perform better than normal buffered
 175 operations (e.g. in virtual environments).
 176 .TP
 177 .B "\-\-use-fsync"
 178 Use fsync call after every written block. This applies for reencryption
 179 log files as well.
 180 .TP
 181 .B "\-\-write-log"
 182 Update log file after every block write. This can slow down reencryption
 183 but will minimize data loss in the case of system crash.
 184 .TP
 185 .B "\-\-batch-mode, \-q"
 186 Suppresses all warnings and reencryption progress output.
 187 .TP
 188 .B "\-\-version"
 189 Show the program version.
 190 .SH RETURN CODES
 191 Cryptsetup-reencrypt returns 0 on success and a non-zero value on error.
 192
 193 Error codes are: 1 wrong parameters, 2 no permission,
 194 3 out of memory, 4 wrong device specified, 5 device already exists
 195 or device is busy.
 196 .SH EXAMPLES
 197 .TP
 198 Reencrypt /dev/sdb1 (change volume key)
 199 cryptsetup-reencrypt /dev/sdb1
 200 .TP
 201 Reencrypt and also change cipher and cipher mode
 202 cryptsetup-reencrypt /dev/sdb1 \-c aes-xts-plain64
 203 .TP
 204 Add LUKS encryption to not yet encrypted device
 205
 206 First, be sure you have space added to disk.
 207
 208 Or alternatively shrink filesystem in advance.
 209 .br
 210 Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
 211
 212 fdisk \-u /dev/sdb # move sdb1 partition end + 4096 sectors
 213 (or use resize2fs or tool for your filesystem and shrink it)
 214
 215 cryptsetup-reencrypt /dev/sdb1 \-\-new \-\-reduce-device-size 4096S
 216 .TP
 217 Remove LUKS encryption completely
 218
 219 cryptsetup-reencrypt /dev/sdb1 \-\-decrypt
 220
 221 .SH REPORTING BUGS
 222 Report bugs, including ones in the documentation, on
 223 the cryptsetup mailing list at <dm-crypt@saout.de>
 224 or in the 'Issues' section on LUKS website.
 225 Please attach the output of the failed command with the
 226 \-\-debug option added.
 227 .SH AUTHORS
 228 Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
 229 .SH COPYRIGHT
 230 Copyright \(co 2012-2015 Milan Broz
 231 .br
 232 Copyright \(co 2012-2013 Red Hat, Inc.
 233
 234 This is free software; see the source for copying conditions.  There is NO
 235 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 236 .SH SEE ALSO
 237 The project website at \fBhttps://gitlab.com/cryptsetup/cryptsetup\fR