cryptsetup-reencrypt(8)

1CRYPTSETUP-REENCRYPT(8)      Maintenance Commands      CRYPTSETUP-REENCRYPT(8)
2
3
4

NAME

6       cryptsetup-reencrypt - tool for offline LUKS device re-encryption
7

SYNOPSIS

9       cryptsetup-reencrypt <options> <device>
10

DESCRIPTION

12       Cryptsetup-reencrypt  can  be  used  to  change reencryption parameters
13       which otherwise require full on-disk data change (re-encryption).
14
15       You can regenerate volume key (the real key used in on-disk  encryption
16       unclocked by passphrase), cipher, cipher mode.
17
18       Cryptsetup-reencrypt  reencrypts  data  on LUKS device in-place. During
19       reencryption process the LUKS device is marked unavailable.
20
21       WARNING: The cryptsetup-reencrypt program is not resistant to  hardware
22       or  kernel  failures during reencryption (you can lose you data in this
23       case).
24
25       ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL.
26       The reencryption can be temporarily suspended (by  TERM  signal  or  by
27       using   ctrl+c)   but   you   need  to  retain  temporary  files  named
28       LUKS-<uuid>.[log|org|new].  LUKS device is unavailable until  reencryp‐
29       tion is finished though.
30
31       Current  working directory must by writable and temporary files created
32       during reencryption must be present.
33
34       For more info about LUKS see cryptsetup(8).
35

OPTIONS

37       To start (or continue) re-encryption for <device> use:
38
39       cryptsetup-reencrypt <device>
40
41       <options> can be [--block-size, --cipher, --hash,  --iter-time,  --use-
42       random   |  --use-urandom,  --key-file,  --key-slot,  --keyfile-offset,
43       --keyfile-size, --tries, --use-directio, --use-fsync, --write-log]
44
45       For detailed description of encryption and key file options see  crypt‐
46       setup(8) man page.
47
48       --verbose, -v
49              Print more information on command execution.
50
51       --debug
52              Run  in debug mode with full diagnostic logs. Debug output lines
53              are always prefixed by '#'.
54
55       --cipher, -c <cipher-spec>
56              Set the cipher specification string.
57
58       --key-size, -s <bits>
59              Set key size in bits. The argument has to be a multiple of  8.
60
61              The possible key-sizes are limited by the cipher and mode used.
62
63              If you are increasing key size, there must be  enough  space  in
64              the LUKS header for enlarged keyslots (data offset must be large
65              enough) or reencryption cannot be performed.
66
67              If there is not enough space for keyslots with new key size, you
68              can   destructively   shrink  device  with  --reduce-device-size
69              option.
70
71       --hash, -h <hash-spec>
72              Specifies the hash used in the LUKS key setup scheme and  volume
73              key digest.
74
75              NOTE: if this parameter is not specified, default hash algorithm
76              is always used for new device header.
77
78       --iter-time, -i <milliseconds>
79              The number of milliseconds to spend with PBKDF2 passphrase  pro‐
80              cessing for the new LUKS header.
81
82       --use-random
83
84       --use-urandom
85              Define which kernel random number generator will be used to cre‐
86              ate the volume key.
87
88       --key-file, -d name
89              Read the passphrase from file.
90
91              WARNING: --key-file option can be used only if  there  only  one
92              active  keyslot,  or alternatively, also if --key-slot option is
93              specified (then all other keyslots will be disabled in new  LUKS
94              device).
95
96              If  this  option  is not used, cryptsetup-reencrypt will ask for
97              all active keyslot passphrases.
98
99       --key-slot, -S <0-7>
100              Specify which key slot is used.
101
102              WARNING: All other keyslots will be disabled if this  option  is
103              used.
104
105       --keyfile-offset value
106              Skip value bytes at the beginning of the key file.
107
108       --keyfile-size, -l
109              Read  a maximum of value bytes from the key file.  Default is to
110              read the whole file up to the compiled-in maximum.
111
112       --keep-key
113              Do not change encryption key, just reencrypt the LUKS header and
114              keyslots.
115
116              This  option  can  be  combined  only with --hash or --iter-time
117              options.
118
119       --tries, -T
120              Number of retries for invalid passphrase entry.
121
122       --block-size, -B value
123              Use re-encryption block size of <value> in MiB.
124
125              Values can be between 1 and 64 MiB.
126
127       --device-size size[units]
128              Instead of real device size, use specified value.
129
130              It means that only specified area (from the start of the  device
131              to the specified size) will be reencrypted.
132
133              WARNING: This is destructive operation.
134
135              If no unit suffix is specified, the size is in bytes.
136
137              Unit  suffix  can  be  S  for  512  byte  sectors,  K/M/G/T  (or
138              KiB,MiB,GiB,TiB) for units with 1024  base  or  KB/MB/GB/TB  for
139              1000 base (SI scale).
140
141              WARNING: This is destructive operation.
142
143       --reduce-device-size size[units]
144              Enlarge data offset to specified value by shrinking device size.
145
146              This  means  that  last  sectors  on the original device will be
147              lost, ciphertext data will be effectively shifted  by  specified
148              number of sectors.
149
150              It  can  be  usefull  if you e.g. added some space to underlying
151              partition (so last sectors contains no data).
152
153              For units suffix see --device-size parameter description.
154
155              WARNING: This is destructive operation and cannot  be  reverted.
156              Use  with  extreme care - shrinked filesystems are usually unre‐
157              coverable.
158
159              You cannot shrink device more than by 64 MiB (131072 sectors).
160
161       --new, N
162              Create new header (encrypt not yet encrypted device).
163
164              This option must be used together with --reduce-device-size.
165
166              WARNING: This is destructive operation and cannot be reverted.
167
168
169       --use-directio
170              Use direct-io (O_DIRECT)  for  all  read/write  data  operations
171              related to block device undergoing reencryption.
172
173              Usefull  if  direct-io  operations  perform  better  than normal
174              buffered operations (e.g. in virtual environments).
175
176       --use-fsync
177              Use fsync call after every written block. This applies for reen‐
178              cryption log files as well.
179
180       --write-log
181              Update  log  file  after  every  block write. This can slow down
182              reencryption but will minimize data loss in the case  of  system
183              crash.
184
185       --batch-mode, -q
186              Suppresses all warnings and reencryption progress output.
187
188       --version
189              Show the program version.
190

RETURN CODES

192       Cryptsetup-reencrypt  returns  0  on  success  and  a non-zero value on
193       error.
194
195       Error codes are: 1 wrong parameters, 2 no permission, 3 out of  memory,
196       4 wrong device specified, 5 device already exists or device is busy.
197

EXAMPLES

199       Reencrypt /dev/sdb1 (change volume key)
200              cryptsetup-reencrypt /dev/sdb1
201
202       Reencrypt and also change cipher and cipher mode
203              cryptsetup-reencrypt /dev/sdb1 -c aes-xts-plain64
204
205       Add LUKS encryption to not yet encrypted device
206
207              First,  be  sure you have space added to disk.  Or alternatively
208              shrink filesystem in advance.
209              Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
210
211              fdisk -u /dev/sdb # move sdb1 partition end + 4096 sectors
212
213              cryptsetup-reencrypt /dev/sdb1 --new --reduce-device-size 4096
214
215

REPORTING BUGS

217       Report bugs, including ones in the  documentation,  on  the  cryptsetup
218       mailing  list at <dm-crypt@saout.de> or in the 'Issues' section on LUKS
219       website.  Please attach the output  of  the  failed  command  with  the
220       --debug option added.
221

AUTHORS

223       Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
224

COPYRIGHT

226       Copyright © 2012-2014 Milan Broz
227       Copyright © 2012-2013 Red Hat, Inc.
228
229       This is free software; see the source for copying conditions.  There is
230       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
231       PURPOSE.
232