man/cryptsetup-reencrypt.8

   1 .TH CRYPTSETUP-REENCRYPT "8" "June 2012" "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 [\-\-block-size, \-\-cipher, \-\-hash, \-\-iter-time,
  40 \-\-use-random | \-\-use-urandom, \-\-key-file, \-\-key-slot, \-\-keyfile-offset,
  41 \-\-keyfile-size, \-\-tries, \-\-use-directio, \-\-use-fsync, \-\-write-log]
  42
  43 For detailed description of encryption and key file options see \fIcryptsetup(8)\fR
  44 man page.
  45 .TP
  46 .B "\-\-verbose, \-v"
  47 Print more information on command execution.
  48 .TP
  49 .B "\-\-debug"
  50 Run in debug mode with full diagnostic logs. Debug output
  51 lines are always prefixed by '#'.
  52 .TP
  53 .B "\-\-cipher, \-c" \fI<cipher-spec>\fR
  54 Set the cipher specification string.
  55 .TP
  56 .B "\-\-key-size, \-s \fI<bits>\fR"
  57 Set key size in bits. The argument has to be a multiple of  8.
  58
  59 The possible key-sizes are limited by the cipher and mode used.
  60
  61 If you are increasing key size, there must be enough space in the LUKS header
  62 for enlarged keyslots (data offset must be large enough) or reencryption
  63 cannot be performed.
  64
  65 If there is not enough space for keyslots with new key size,
  66 you can destructively shrink device with \-\-reduce-device-size option.
  67 .TP
  68 .B "\-\-hash, \-h \fI<hash-spec>\fR"
  69 Specifies the hash used in the LUKS key setup scheme and volume key digest.
  70 .TP
  71 .B "\-\-iter-time, \-i \fI<milliseconds>\fR"
  72 The number of milliseconds to spend with PBKDF2 passphrase processing for the
  73 new LUKS header.
  74 .TP
  75 .B "\-\-use-random"
  76 .TP
  77 .B "\-\-use-urandom"
  78 Define which kernel random number generator will be used to create the volume key.
  79 .TP
  80 .B "\-\-key-file, \-d \fIname\fR"
  81 Read the passphrase from file.
  82
  83 WARNING: \-\-key-file option can be used only if there only one active keyslot,
  84 or alternatively, also if \-\-key-slot option is specified (then all other keyslots
  85 will be disabled in new LUKS device).
  86
  87 If this option is not used, cryptsetup-reencrypt will ask for all active keyslot
  88 passphrases.
  89 .TP
  90 .B "\-\-key-slot, \-S <0-7>"
  91 Specify which key slot is used.
  92
  93 WARNING: All other keyslots will be disabled if this option is used.
  94 .TP
  95 .B "\-\-keyfile-offset \fIvalue\fR"
  96 Skip \fIvalue\fR bytes at the beginning of the key file.
  97 .TP
  98 .B "\-\-keyfile-size, \-l"
  99 Read a maximum of \fIvalue\fR bytes from the key file.
 100 Default is to read the whole file up to the compiled-in
 101 maximum.
 102 .TP
 103 .B "\-\-tries, \-T"
 104 Number of retries for invalid passphrase entry.
 105 .TP
 106 .B "\-\-block-size, \-B \fIvalue\fR"
 107 Use re-encryption block size of <value> in MiB.
 108
 109 Values can be between 1 and 64 MiB.
 110 .TP
 111 .B "\-\-reduce-device-size \fInumber of 512 bytes sectors\fR"
 112 Enlarge data offset for specified value of sectors by shrinking
 113 device size.
 114
 115 This means that last sectors on the original device will be lost,
 116 ciphertext data will be effectively shifted by specified
 117 number of sectors.
 118
 119 It can be usefull if you e.g. added some space to underlying
 120 partition (so last sectors contains no data).
 121
 122 WARNING: This is destructive operation and cannot be reverted.
 123 Use with extreme care - shrinked filesystems are usually unrecoverable.
 124
 125 You cannot shrink device more than by 64 MiB (131072 sectors).
 126 .TP
 127 .B "\-\-new, N"
 128 Create new header (encrypt not yet encrypted device).
 129
 130 This option must be used together with \-\-reduce-device-size.
 131
 132 WARNING: This is destructive operation and cannot be reverted.
 133
 134 .TP
 135 .B "\-\-use-directio"
 136 Use direct-io (O_DIRECT) for all read/write data operations.
 137
 138 Usefull if direct-io operations perform better than normal buffered
 139 operations (e.g. in virtual environments).
 140 .TP
 141 .B "\-\-use-fsync"
 142 Use fsync call after every written block.
 143 .TP
 144 .B "\-\-write-log"
 145 Update log file after every block write. This can slow down reencryption
 146 but will minimize data loss in the case of system crash.
 147 .TP
 148 .B "\-\-batch-mode, \-q"
 149 Suppresses all warnings and reencryption progress output.
 150 .TP
 151 .B "\-\-version"
 152 Show the program version.
 153 .SH RETURN CODES
 154 Cryptsetup-reencrypt returns 0 on success and a non-zero value on error.
 155
 156 Error codes are: 1 wrong parameters, 2 no permission,
 157 3 out of memory, 4 wrong device specified, 5 device already exists
 158 or device is busy.
 159 .SH EXAMPLES
 160 .TP
 161 Reencrypt /dev/sdb1 (change volume key)
 162 cryptsetup-reencrypt /dev/sdb1
 163 .TP
 164 Reencrypt and also change cipher and cipher mode
 165 cryptsetup-reencrypt /dev/sdb1 -c aes-xts-plain64
 166 .TP
 167 Add LUKS encryption to not yet encrypted device
 168
 169 First, be sure you have space added to disk.
 170 Or alternatively shrink filesystem in advance.
 171 .br
 172 Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
 173
 174 fdisk -u /dev/sdb # move sdb1 partition end + 4096 sectors
 175
 176 cryptsetup-reencrypt /dev/sdb1 --new --reduce-device-size 4096
 177
 178 .SH REPORTING BUGS
 179 Report bugs, including ones in the documentation, on
 180 the cryptsetup mailing list at <dm-crypt@saout.de>
 181 or in the 'Issues' section on LUKS website.
 182 Please attach the output of the failed command with the
 183 \-\-debug option added.
 184 .SH AUTHORS
 185 Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
 186 .SH COPYRIGHT
 187 Copyright \(co 2012 Milan Broz
 188 .br
 189 Copyright \(co 2012 Red Hat, Inc.
 190
 191 This is free software; see the source for copying conditions.  There is NO
 192 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 193 .SH SEE ALSO
 194 The project website at \fBhttp://code.google.com/p/cryptsetup/\fR