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       NOTE: If you're looking for LUKS2  online  reencryption  manual  please
22       read  cryptsetup(8)  man page instead (see reencrypt action). This page
23       is for legacy offline reencryption utility only.
24
25       WARNING: The cryptsetup-reencrypt program is not resistant to  hardware
26       or  kernel failures during reencryption (you can lose your data in this
27       case).
28
29       ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL.
30       The reencryption can be temporarily suspended (by  TERM  signal  or  by
31       using   ctrl+c)   but   you   need  to  retain  temporary  files  named
32       LUKS-<uuid>.[log|org|new].  LUKS device is unavailable until  reencryp‐
33       tion is finished though.
34
35       Current  working directory must be writable and temporary files created
36       during reencryption must be present.
37
38       For more info about LUKS see cryptsetup(8).
39

OPTIONS

41       To start (or continue) re-encryption for <device> use:
42
43       cryptsetup-reencrypt <device>
44
45       <options> can be [--batch-mode, --block-size,  --cipher  |  --keep-key,
46       --debug,     --device-size,    --hash,    --header,    --iter-time    |
47       --pbkdf-force-iterations, --key-file,  --key-size,  --key-slot,  --key‐
48       file-offset,   --keyfile-size,   --master-key-file,  --tries,  --pbkdf,
49       --pbkdf-memory, --pbkdf-parallel, --progress-frequency, --use-directio,
50       --use-random  | --use-urandom, --use-fsync, --uuid, --verbose, --write-
51       log]
52
53       To encrypt data on (not yet encrypted) device, use --new in combination
54       with --reduce-device-size or with --header option for detached header.
55
56       To remove encryption from device, use --decrypt.
57
58       For  detailed description of encryption and key file options see crypt‐
59       setup(8) man page.
60
61       --batch-mode, -q
62              Suppresses all warnings and reencryption progress output.
63
64       --block-size, -B value
65              Use re-encryption block size of <value> in MiB.
66
67              Values can be between 1 and 64 MiB.
68
69       --cipher, -c <cipher-spec>
70              Set the cipher specification string.
71
72       --debug
73              Run in debug mode with full diagnostic logs. Debug output  lines
74              are always prefixed by '#'.
75
76       --decrypt
77              Remove  encryption  (decrypt already encrypted device and remove
78              LUKS header).
79
80              WARNING: This is destructive operation and cannot be reverted.
81
82       --device-size size[units]
83              Instead of real device size, use specified value.
84
85              It means that only specified area (from the start of the  device
86              to the specified size) will be reencrypted.
87
88              If no unit suffix is specified, the size is in bytes.
89
90              Unit  suffix  can  be  S  for  512  byte  sectors,  K/M/G/T  (or
91              KiB,MiB,GiB,TiB) for units with 1024  base  or  KB/MB/GB/TB  for
92              1000 base (SI scale).
93
94              WARNING: This is destructive operation.
95
96       --hash, -h <hash-spec>
97              Specifies the hash used in the LUKS1 key setup scheme and volume
98              key digest.
99
100              NOTE: if this parameter is not specified, default hash algorithm
101              is always used for new LUKS1 device header.
102
103              NOTE:  with  LUKS2  format this option is only relevant when new
104              keyslot pbkdf algorithm is set to PBKDF2 (see --pbkdf).
105
106       --header <LUKS header file>
107              Use a detached (separated) metadata device  or  file  where  the
108              LUKS  header  is stored. This option allows one to store cipher‐
109              text and LUKS header on different devices.
110
111              WARNING: There is no check whether the ciphertext device  speci‐
112              fied  actually  belongs to the header given.  If used with --new
113              option, the header file will created (or overwritten).  Use with
114              care.
115
116       --iter-time, -i <milliseconds>
117              The  number of milliseconds to spend with PBKDF2 passphrase pro‐
118              cessing for the new LUKS header.
119
120       --keep-key
121              Do not change encryption key, just reencrypt the LUKS header and
122              keyslots.
123
124              This  option  can  be  combined  only  with --hash, --iter-time,
125              --pbkdf-force-iterations, --pbkdf (LUKS2  only),  --pbkdf-memory
126              (Argon2i/id and LUKS2 only) and --pbkdf-parallel (Argon2i/id and
127              LUKS2 only) options.
128
129       --key-file, -d name
130              Read the passphrase from file.
131
132              WARNING: --key-file option can be used only if there is only one
133              active  keyslot,  or alternatively, also if --key-slot option is
134              specified (then all other keyslots will be disabled in new  LUKS
135              device).
136
137              If  this  option  is not used, cryptsetup-reencrypt will ask for
138              all active keyslot passphrases.
139
140       --key-size, -s <bits>
141              Set key size in bits. The argument has to be a multiple of  8.
142
143              The possible key-sizes are limited by the cipher and mode used.
144
145              If you are increasing key size, there must be  enough  space  in
146              the LUKS header for enlarged keyslots (data offset must be large
147              enough) or reencryption cannot be performed.
148
149              If there is not enough space for keyslots with new key size, you
150              can   destructively   shrink  device  with  --reduce-device-size
151              option.
152
153       --key-slot, -S <0-MAX>
154              Specify which key slot is used. For LUKS1, max keyslot number is
155              7. For LUKS2, it's 31.
156
157              WARNING:  All  other keyslots will be disabled if this option is
158              used.
159
160       --keyfile-offset value
161              Skip value bytes at the beginning of the key file.
162
163       --keyfile-size, -l
164              Read a maximum of value bytes from the key file.  Default is  to
165              read the whole file up to the compiled-in maximum.
166
167       --master-key-file
168              Use new volume (master) key stored in a file.
169
170       --new, -N
171              Create new header (encrypt not yet encrypted device).
172
173              This option must be used together with --reduce-device-size.
174
175              WARNING: This is destructive operation and cannot be reverted.
176
177       --pbkdf
178              Set Password-Based Key Derivation Function (PBKDF) algorithm for
179              LUKS keyslot.  The PBKDF can be: pbkdf2, argon2i for Argon2i  or
180              argon2id for Argon2id.
181
182              For LUKS1, only pbkdf2 is accepted (no need to use this option).
183
184       --pbkdf-force-iterations <num>
185              Avoid PBKDF benchmark and set time cost (iterations) directly.
186
187       --pbkdf-memory <number>
188              Set  the memory cost for PBKDF (for Argon2i/id the number repre‐
189              sents kilobytes).  Note that it is maximal value,  PBKDF  bench‐
190              mark  or available physical memory can decrease it.  This option
191              is not available for PBKDF2.
192
193       --pbkdf-parallel <number>
194              Set the parallel cost for PBKDF (number of threads,  up  to  4).
195              Note  that it is maximal value, it is decreased automatically if
196              CPU online count is lower.  This option  is  not  available  for
197              PBKDF2.
198
199       --progress-frequency <seconds>
200              Print separate line every <seconds> with reencryption progress.
201
202       --reduce-device-size size[units]
203              Enlarge data offset to specified value by shrinking device size.
204
205              This  means  that  last  sectors  on the original device will be
206              lost, ciphertext data will be effectively shifted  by  specified
207              number of sectors.
208
209              It can be useful if you e.g. added some space to underlying par‐
210              tition (so last sectors contains no data).
211
212              For units suffix see --device-size parameter description.
213
214              You cannot shrink device more than by 64 MiB (131072 sectors).
215
216              WARNING: This is destructive operation and cannot  be  reverted.
217              Use  with extreme care - shrunk filesystems are usually unrecov‐
218              erable.
219
220       --tries, -T
221              Number of retries for invalid passphrase entry.
222
223       --type <type>
224              Use only while encrypting not yet encrypted device (see --new).
225
226              Specify LUKS version when performing in-place encryption. If the
227              parameter  is omitted default value (LUKS1) is used. Type may be
228              one of: luks (default), luks1 or luks2.
229
230       --use-directio
231              Use direct-io (O_DIRECT)  for  all  read/write  data  operations
232              related to block device undergoing reencryption.
233
234              Useful  if  direct-io  operations  perform  better  than  normal
235              buffered operations (e.g. in virtual environments).
236
237       --use-fsync
238              Use fsync call after every written block. This applies for reen‐
239              cryption log files as well.
240
241       --use-random
242
243       --use-urandom
244              Define which kernel random number generator will be used to cre‐
245              ate the volume key.
246
247       --uuid <uuid>
248              Use only while resuming an interrupted decryption  process  (see
249              --decrypt).
250
251              To  find  out  what  <uuid>  to  pass  look  for temporary files
252              LUKS-<uuid>.[|log|org|new]   of   the   interrupted   decryption
253              process.
254
255       --verbose, -v
256              Print more information on command execution.
257
258       --version
259              Show the program version.
260
261       --write-log
262              Update  log  file  after  every  block write. This can slow down
263              reencryption but will minimize data loss in the case  of  system
264              crash.
265
266

RETURN CODES

268       Cryptsetup-reencrypt  returns  0  on  success  and  a non-zero value on
269       error.
270
271       Error codes are: 1 wrong parameters, 2 no permission, 3 out of  memory,
272       4 wrong device specified, 5 device already exists or device is busy.
273

EXAMPLES

275       Reencrypt /dev/sdb1 (change volume key)
276              cryptsetup-reencrypt /dev/sdb1
277
278       Reencrypt and also change cipher and cipher mode
279              cryptsetup-reencrypt /dev/sdb1 -c aes-xts-plain64
280
281       Add LUKS encryption to not yet encrypted device
282
283              First, be sure you have space added to disk.
284
285              Or alternatively shrink filesystem in advance.
286              Here we need 4096 512-bytes sectors (enough for 2x128 bit key).
287
288              fdisk  -u  /dev/sdb # move sdb1 partition end + 4096 sectors (or
289              use resize2fs or tool for your filesystem and shrink it)
290
291              cryptsetup-reencrypt /dev/sdb1 --new --reduce-device-size 4096S
292
293       Remove LUKS encryption completely
294
295              cryptsetup-reencrypt /dev/sdb1 --decrypt
296
297

REPORTING BUGS

299       Report bugs, including ones in the  documentation,  on  the  cryptsetup
300       mailing  list at <dm-crypt@saout.de> or in the 'Issues' section on LUKS
301       website.  Please attach the output  of  the  failed  command  with  the
302       --debug option added.
303

AUTHORS

305       Cryptsetup-reencrypt was written by Milan Broz <gmazyland@gmail.com>.
306
308       Copyright © 2012-2020 Milan Broz
309       Copyright © 2012-2020 Red Hat, Inc.
310
311       This is free software; see the source for copying conditions.  There is
312       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
313       PURPOSE.
314

SEE ALSO

316       The project website at https://gitlab.com/cryptsetup/cryptsetup
317
318
319
320cryptsetup-reencrypt             January 2019          CRYPTSETUP-REENCRYPT(8)
Impressum