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

RETURN CODES

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

EXAMPLES

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

REPORTING BUGS

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

AUTHORS

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

SEE ALSO

313       The project website at https://gitlab.com/cryptsetup/cryptsetup
314
315
316
317cryptsetup-reencrypt             January 2019          CRYPTSETUP-REENCRYPT(8)
Impressum