1CRYPTSETUP-REENCRYPT(8) Maintenance Commands CRYPTSETUP-REENCRYPT(8)
2
6 cryptsetup-reencrypt - reencrypt LUKS encrypted volumes in-place
7
9 cryptsetup reencrypt [<options>] <device> or --active-name <name>
10 [<new_name>]
11
13 Run LUKS device reencryption.
14 There are 3 basic modes of operation:
16 • device reencryption (reencrypt)
18 • device encryption (reencrypt --encrypt/--new/-N)
20 • device decryption (reencrypt --decrypt)
22 <device> or --active-name <name> (LUKS2 only) is mandatory parameter.
24 Cryptsetup reencrypt action can be used to change reencryption
26 parameters which otherwise require full on-disk data change
27 (re-encryption). The reencrypt action reencrypts data on LUKS device
28 in-place.
29 You can regenerate volume key (the real key used in on-disk encryption
31 unclocked by passphrase), cipher, cipher mode or encryption sector size
32 (LUKS2 only).
33 Reencryption process may be safely interrupted by a user via SIGINT
35 signal (ctrl+c). Same applies to SIGTERM signal (i.e. issued by systemd
36 during system shutdown).
37 For in-place encryption mode, the reencrypt action additionally takes
39 all options available for luksFormat action for respective LUKS version
40 (see cryptsetup-luksFormat man page for more details). See
41 cryptsetup-luksFormat(8).
42 NOTE that for encrypt and decrypt mode, the whole device must be
44 treated as unencrypted — there are no quarantees of confidentiality as
45 part of the device contains plaintext.
46 ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS ACTION ON
48 LUKS DEVICE.
49 <options> can be [--batch-mode, --block-size, --cipher, --debug,
51 --debug-json, --decrypt, --device-size, --disable-locks, --encrypt,
52 --force-offline-reencrypt, --hash, --header, --hotzone-size,
53 --iter-time, --init-only, --keep-key, --key-file, --key-size,
54 --key-slot, --keyfile-offset, --keyfile-size, --tries, --timeout,
55 --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel,
56 --progress-frequency, --progress-json, --reduce-device-size,
57 --resilience, --resilience-hash, --resume-only, --sector-size,
58 --use-directio, --use-random, --use-urandom, --use-fsync, --uuid,
59 --verbose, --volume-key-file, --write-log].
60
62 With <device> parameter cryptsetup looks up active <device> dm mapping.
63 If no active mapping is detected, it starts offline LUKS2 reencryption
64 otherwise online reencryption takes place.
65 To resume already initialized or interrupted reencryption, just run the
67 cryptsetup reencrypt command again to continue the reencryption
68 operation. Reencryption may be resumed with different --resilience or
69 --hotzone-size unless implicit datashift resilience mode is used:
70 either encrypt mode with --reduce-device-size option or decrypt mode
71 with original LUKS2 header exported in --header file.
72 If the reencryption process was interrupted abruptly (reencryption
74 process crash, system crash, poweroff) it may require recovery. The
75 recovery is currently run automatically on next activation (action
76 open) when needed or explicitly by user (action repair).
77 Optional parameter <new_name> takes effect only with encrypt option and
79 it activates device <new_name> immediately after encryption
80 initialization gets finished. That’s useful when device needs to be
81 ready as soon as possible and mounted (used) before full data area
82 encryption is completed.
83
85 Current working directory must be writable and temporary files created
86 during reencryption must be present. During reencryption process the
87 LUKS1 device is marked unavailable and must be offline (no dm-crypt
88 mapping or mounted filesystem).
89 WARNING: The LUKS1 reencryption code is not resistant to hardware or
91 kernel failures during reencryption (you can lose your data in this
92 case).
93
95 --block-size value (LUKS1 only)
96 Use re-encryption block size of value in MiB.
97 Values can be between 1 and 64 MiB.
99 --use-directio (LUKS1 only)
101 Use direct-io (O_DIRECT) for all read/write data operations related
102 to block device undergoing reencryption.
103 Useful if direct-io operations perform better than normal buffered
105 operations (e.g. in virtual environments).
106 --use-fsync (LUKS1 only)
108 Use fsync call after every written block. This applies for
109 reencryption log files as well.
110 --write-log (LUKS1 only)
112 Update log file after every block write. This can slow down
113 reencryption but will minimize data loss in the case of system
114 crash.
115 --type <device-type>
117 Specifies required (encryption mode) or expected (other modes) LUKS
118 format. Accepts only luks1 or luks2.
119 --hash, -h <hash-spec>
121 LUKS1: Specifies the hash used in the LUKS1 key setup scheme and
122 volume key digest.
123 NOTE: if this parameter is not specified, default hash algorithm is
125 always used for new LUKS1 device header.
126 LUKS2: Ignored unless new keyslot pbkdf algorithm is set to PBKDF2
128 (see --pbkdf).
129 --cipher, -c <cipher-spec>
131 LUKS2: Set the cipher specification string for data segment only.
132 LUKS1: Set the cipher specification string for data segment and
134 keyslots.
135 NOTE: In encrypt mode, if cipher specification is omitted the
137 default cipher is applied. In reencrypt mode, if no new cipher
138 specification is requested, the existing cipher will remain in use.
139 Unless the existing cipher was "cipher_null". In that case default
140 cipher would be applied as in encrypt mode.
141 cryptsetup --help shows the compiled-in defaults.
143 If a hash is part of the cipher specification, then it is used as
145 part of the IV generation. For example, ESSIV needs a hash
146 function, while "plain64" does not and hence none is specified.
147 For XTS mode you can optionally set a key size of 512 bits with the
149 -s option. Key size for XTS mode is twice that for other modes for
150 the same security level.
151 --verify-passphrase, -y
153 When interactively asking for a passphrase, ask for it twice and
154 complain if both inputs do not match. Ignored on input from file or
155 stdin.
156 --key-file, -d name
158 Read the passphrase from file.
159 If the name given is "-", then the passphrase will be read from
161 stdin. In this case, reading will not stop at newline characters.
162 WARNING: --key-file option can be used only if there is only one
164 active keyslot, or alternatively, also if --key-slot option is
165 specified (then all other keyslots will be disabled in new LUKS
166 device).
167 If this option is not used, cryptsetup will ask for all active
169 keyslot passphrases.
170 --keyfile-offset value
172 Skip value bytes at the beginning of the key file.
173 --keyfile-size, -l value
175 Read a maximum of value bytes from the key file. The default is to
176 read the whole file up to the compiled-in maximum that can be
177 queried with --help. Supplying more data than the compiled-in
178 maximum aborts the operation.
179 This option is useful to cut trailing newlines, for example. If
181 --keyfile-offset is also given, the size count starts after the
182 offset.
183 --volume-key-file, --master-key-file (OBSOLETE alias)
185 Use (set) new volume key stored in a file.
186 WARNING: If you create your own volume key, you need to make sure
187 to do it right. Otherwise, you can end up with a low-entropy or
188 otherwise partially predictable volume key which will compromise
189 security.
190 --use-random, --use-urandom
192 Define which kernel random number generator will be used to create
193 the volume key.
194 --keep-key
196 LUKS2: Do not change effective volume key and change other
197 parameters provided it is requested.
198 LUKS1: Reencrypt only the LUKS1 header and keyslots. Skips data
200 in-place reencryption.
201 --key-slot, -S <0-N>
203 For LUKS operations that add key material, this option allows you
204 to specify which key slot is selected for the new key.
205 For reencryption mode it selects specific keyslot (and passphrase)
207 that can be used to unlock new volume key. If used all other
208 keyslots get removed after reencryption operation is finished.
209 The maximum number of key slots depends on the LUKS version. LUKS1
211 can have up to 8 key slots. LUKS2 can have up to 32 key slots based
212 on key slot area size and key size, but a valid key slot ID can
213 always be between 0 and 31 for LUKS2.
214 --key-size, -s bits
216 Sets key size in bits. The argument has to be a multiple of 8. The
217 possible key-sizes are limited by the cipher and mode used.
218 See /proc/crypto for more information. Note that key-size in
220 /proc/crypto is stated in bytes.
221 LUKS1: If you are increasing key size, there must be enough space
223 in the LUKS header for enlarged keyslots (data offset must be large
224 enough) or reencryption cannot be performed.
225 If there is not enough space for keyslots with new key size, you
227 can destructively shrink device with --reduce-device-size option.
228 --offset, -o <number of 512 byte sectors>
230 Start offset in the backend device in 512-byte sectors. This option
231 is only relevant for the encrypt mode.
232 The --offset option sets the data offset (payload) of data device
234 and must be aligned to 4096-byte sectors (must be multiple of 8).
235 This option cannot be combined with --align-payload option.
236 --device-size size[units]
238 Instead of real device size, use specified value. It means that
239 only specified area (from the start of the device to the specified
240 size) will be reencrypted.
241 WARNING: This is destructive operation. Data beyond --device-size
243 limit may be lost after operation gets finished.
244 If no unit suffix is specified, the size is in bytes.
246 Unit suffix can be S for 512 byte sectors, K/M/G/T (or
248 KiB,MiB,GiB,TiB) for units with 1024 base or KB/MB/GB/TB for 1000
249 base (SI scale).
250 --pbkdf <PBKDF spec>
252 Set Password-Based Key Derivation Function (PBKDF) algorithm for
253 LUKS keyslot. The PBKDF can be: pbkdf2 (for PBKDF2 according to
254 RFC2898), argon2i for Argon2i or argon2id for Argon2id (see Argon2
255 <https://www.cryptolux.org/index.php/Argon2> for more info).
256 For LUKS1, only PBKDF2 is accepted (no need to use this option).
258 The default PBKDF for LUKS2 is set during compilation time and is
259 available in cryptsetup --help output.
260 A PBKDF is used for increasing dictionary and brute-force attack
262 cost for keyslot passwords. The parameters can be time, memory and
263 parallel cost.
264 For PBKDF2, only time cost (number of iterations) applies. For
266 Argon2i/id, there is also memory cost (memory required during the
267 process of key derivation) and parallel cost (number of threads
268 that run in parallel during the key derivation.
269 Note that increasing memory cost also increases time, so the final
271 parameter values are measured by a benchmark. The benchmark tries
272 to find iteration time (--iter-time) with required memory cost
273 --pbkdf-memory. If it is not possible, the memory cost is decreased
274 as well. The parallel cost --pbkdf-parallel is constant and is
275 checked against available CPU cores.
276 You can see all PBKDF parameters for particular LUKS2 keyslot with
278 cryptsetup-luksDump(8) command.
279 NOTE: If you do not want to use benchmark and want to specify all
281 parameters directly, use --pbkdf-force-iterations with
282 --pbkdf-memory and --pbkdf-parallel. This will override the values
283 without benchmarking. Note it can cause extremely long unlocking
284 time. Use only in specific cases, for example, if you know that the
285 formatted device will be used on some small embedded system.
286 MINIMAL AND MAXIMAL PBKDF COSTS: For PBKDF2, the minimum iteration
288 count is 1000 and maximum is 4294967295 (maximum for 32bit unsigned
289 integer). Memory and parallel costs are unused for PBKDF2. For
290 Argon2i and Argon2id, minimum iteration count (CPU cost) is 4 and
291 maximum is 4294967295 (maximum for 32bit unsigned integer). Minimum
292 memory cost is 32 KiB and maximum is 4 GiB. (Limited by addressable
293 memory on some CPU platforms.) If the memory cost parameter is
294 benchmarked (not specified by a parameter) it is always in range
295 from 64 MiB to 1 GiB. The parallel cost minimum is 1 and maximum 4
296 (if enough CPUs cores are available, otherwise it is decreased).
297 --iter-time, -i <number of milliseconds>
299 The number of milliseconds to spend with PBKDF passphrase
300 processing for the new LUKS header.
301 --pbkdf-memory <number>
303 Set the memory cost for PBKDF (for Argon2i/id the number represents
304 kilobytes). Note that it is maximal value, PBKDF benchmark or
305 available physical memory can decrease it. This option is not
306 available for PBKDF2.
307 --pbkdf-parallel <number>
309 Set the parallel cost for PBKDF (number of threads, up to 4). Note
310 that it is maximal value, it is decreased automatically if CPU
311 online count is lower. This option is not available for PBKDF2.
312 --pbkdf-force-iterations <num>
314 Avoid PBKDF benchmark and set time cost (iterations) directly. It
315 can be used for LUKS/LUKS2 device only. See --pbkdf option for more
316 info.
317 --progress-frequency seconds
319 Print separate line every seconds with reencryption progress.
320 --progress-json
322 Prints progress data in JSON format suitable mostly for machine
323 processing. It prints separate line every half second (or based on
324 --progress-frequency value). The JSON output looks as follows
325 during progress (except it’s compact single line):
326 {
328 "device":"/dev/sda" // backing device or file
329 "device_bytes":"8192", // bytes of I/O so far
330 "device_size":"44040192", // total bytes of I/O to go
331 "speed":"126877696", // calculated speed in bytes per second (based on progress so far)
332 "eta_ms":"2520012" // estimated time to finish an operation in milliseconds
333 "time_ms":"5561235" // total time spent in IO operation in milliseconds
334 }
335 Note on numbers in JSON output: Due to JSON parsers limitations all
337 numbers are represented in a string format due to need of full
338 64bit unsigned integers.
339 --timeout, -t <number of seconds>
341 The number of seconds to wait before timeout on passphrase input
342 via terminal. It is relevant every time a passphrase is asked. It
343 has no effect if used in conjunction with --key-file.
344 This option is useful when the system should not stall if the user
346 does not input a passphrase, e.g. during boot. The default is a
347 value of 0 seconds, which means to wait forever.
348 --tries, -T
350 How often the input of the passphrase shall be retried. The default
351 is 3 tries.
352 --align-payload <number of 512 byte sectors>
354 Align payload at a boundary of value 512-byte sectors.
355 If not specified, cryptsetup tries to use the topology info
357 provided by the kernel for the underlying device to get the optimal
358 alignment. If not available (or the calculated value is a multiple
359 of the default) data is by default aligned to a 1MiB boundary (i.e.
360 2048 512-byte sectors).
361 For a detached LUKS header, this option specifies the offset on the
363 data device. See also the --header option.
364 WARNING: This option is DEPRECATED and has often unexpected impact
366 to the data offset and keyslot area size (for LUKS2) due to the
367 complex rounding. For fixed data device offset use --offset option
368 instead.
369 --uuid <UUID>
371 When used in encryption mode use the provided UUID for the new LUKS
372 header instead of generating a new one.
373 LUKS1 (only in decryption mode): To find out what UUID to pass look
375 for temporary files LUKS-UUID.[|log|org|new] of the interrupted
376 decryption process.
377 The UUID must be provided in the standard UUID format, e.g.
379 12345678-1234-1234-1234-123456789abc.
380 --header <device or file storing the LUKS header>
382 Use a detached (separated) metadata device or file where the LUKS
383 header is stored. This option allows one to store ciphertext and
384 LUKS header on different devices.
385 If used with --encrypt/--new option, the header file will be
387 created (or overwritten). Use with care.
388 LUKS2: For decryption mode the option may be used to export
390 original LUKS2 header to a detached file. The passed future file
391 must not exist at the time of initializing the decryption
392 operation. This frees space in head of data device so that data can
393 be moved at original LUKS2 header location. Later on decryption
394 operation continues as if the ordinary detached header was passed.
395 WARNING: Never put exported header file in a filesystem on top of
397 device you are about to decrypt! It would cause a deadlock.
398 --force-offline-reencrypt (LUKS2 only)
400 Bypass active device auto-detection and enforce offline
401 reencryption.
402 This option is useful especially for reencryption of LUKS2 images
404 put in files (auto-detection is not reliable in this scenario).
405 It may also help in case active device auto-detection on particular
407 data device does not work or report errors.
408 WARNING: Use with extreme caution! This may destroy data if the
410 device is activated and/or actively used.
411 --force-password
413 Do not use password quality checking for new LUKS passwords.
414 This option is ignored if cryptsetup is built without password
416 quality checking support.
417 For more info about password quality check, see the manual page for
419 pwquality.conf(5) and passwdqc.conf(5).
420 --disable-locks
422 Disable lock protection for metadata on disk. This option is valid
423 only for LUKS2 and ignored for other formats.
424 NOTE: With locking disabled LUKS2 images in files can be fully
426 (re)encrypted offline without need for super user privileges
427 provided used block ciphers are available in crypto backend.
428 WARNING: Do not use this option unless you run cryptsetup in a
430 restricted environment where locking is impossible to perform
431 (where /run directory cannot be used).
432 --disable-keyring
434 Do not load volume key in kernel keyring and store it directly in
435 the dm-crypt target instead. This option is supported only for the
436 LUKS2 type.
437 --sector-size bytes (LUKS2 only)
439 Reencrypt device with new encryption sector size enforced.
440 WARNING: Increasing encryption sector size may break hosted
442 filesystem. Do not run reencryption with --force-offline-reencrypt
443 if unsure what block size was filesystem formatted with.
444 --label <LABEL> --subsystem <SUBSYSTEM>
446 Set label and subsystem description for LUKS2 device. The label and
447 subsystem are optional fields and can be later used in udev scripts
448 for triggering user actions once the device marked by these labels
449 is detected.
450 --luks2-metadata-size <size>
452 This option can be used to enlarge the LUKS2 metadata (JSON) area.
453 The size includes 4096 bytes for binary metadata (usable JSON area
454 is smaller of the binary area). According to LUKS2 specification,
455 only these values are valid: 16, 32, 64, 128, 256, 512, 1024, 2048
456 and 4096 kB The <size> can be specified with unit suffix (for
457 example 128k).
458 --luks2-keyslots-size <size>
460 This option can be used to set specific size of the LUKS2 binary
461 keyslot area (key material is encrypted there). The value must be
462 aligned to multiple of 4096 bytes with maximum size 128MB. The
463 <size> can be specified with unit suffix (for example 128k).
464 --keyslot-cipher <cipher-spec>
466 This option can be used to set specific cipher encryption for the
467 LUKS2 keyslot area.
468 --keyslot-key-size <bits>
470 This option can be used to set specific key size for the LUKS2
471 keyslot area.
472 --encrypt, --new, -N
474 Initialize (and run) device in-place encryption mode.
475 --decrypt
477 Initialize (and run) device decryption mode.
478 --init-only (LUKS2 only)
480 Initialize reencryption (any mode) operation in LUKS2 metadata only
481 and exit. If any reencrypt operation is already initialized in
482 metadata, the command with --init-only parameter fails.
483 --resume-only (LUKS2 only)
485 Resume reencryption (any mode) operation already described in LUKS2
486 metadata. If no reencrypt operation is initialized, the command
487 with --resume-only parameter fails. Useful for resuming reencrypt
488 operation without accidentally triggering new reencryption
489 operation.
490 --resilience mode (LUKS2 only)
492 Reencryption resilience mode can be one of checksum, journal or
493 none.
494 checksum: default mode, where individual checksums of ciphertext
496 hotzone sectors are stored, so the recovery process can detect
497 which sectors were already reencrypted. It requires that the device
498 sector write is atomic.
499 journal: the hotzone is journaled in the binary area (so the data
501 are written twice).
502 none: performance mode. There is no protection and the only way
504 it’s safe to interrupt the reencryption is similar to old offline
505 reencryption utility.
506 Resilience modes can be changed unless datashift mode is used for
508 operation initialization (encryption with --reduce-device-size
509 option)
510 --resilience-hash hash (LUKS2 only)
512 The hash algorithm used with "--resilience checksum" only. The
513 default hash is sha256. With other resilience modes, the hash
514 parameter is ignored.
515 --hotzone-size size (LUKS2 only)
517 This option can be used to set an upper limit on the size of
518 reencryption area (hotzone). The size can be specified with unit
519 suffix (for example 50M). Note that actual hotzone size may be less
520 than specified <size> due to other limitations (free space in
521 keyslots area or available memory).
522 With decryption mode for devices with LUKS2 header placed in head
524 of data device, the option specifies how large is the first data
525 segment moved from original data offset pointer.
526 --reduce-device-size size
528 This means that last size sectors on the original device will be
529 lost, data will be effectively shifted by specified number of
530 sectors.
531 It could be useful if you added some space to underlying partition
533 or logical volume (so last size sectors contains no data).
534 For units suffix see --device-size parameter description.
536 WARNING: This is a destructive operation and cannot be reverted.
538 Use with extreme care - accidentally overwritten filesystems are
539 usually unrecoverable.
540 LUKS2: Initialize LUKS2 reencryption with data device size
542 reduction (currently only encryption mode is supported).
543 Recommended minimal size is twice the default LUKS2 header size
545 (--reduce-device-size 32M) for encryption mode.
546 LUKS1: Enlarge data offset to specified value by shrinking device
548 size.
549 You cannot shrink device more than by 64 MiB (131072 sectors).
551 --batch-mode, -q
553 Suppresses all confirmation questions. Use with care!
554 If the --verify-passphrase option is not specified, this option
556 also switches off the passphrase verification.
557 --debug or --debug-json
559 Run in debug mode with full diagnostic logs. Debug output lines are
560 always prefixed by #.
561 If --debug-json is used, additional LUKS2 JSON data structures are
563 printed.
564 --version, -V
566 Show the program version.
567 --usage
569 Show short option help.
570 --help, -?
572 Show help text and default parameters.
573
575 NOTE: You may drop --type luks2 option as long as LUKS2 format is
576 default.
577 LUKS2 ENCRYPTION EXAMPLES
579 Encrypt LUKS2 device (in-place). Make sure last 32 MiB on
580 /dev/plaintext is unused (e.g.: does not contain filesystem data):
581 cryptsetup reencrypt --encrypt --type luks2 --reduce-device-size 32m
583 /dev/plaintext_device
584 Encrypt LUKS2 device (in-place) with detached header put in a file:
586 cryptsetup reencrypt --encrypt --type luks2 --header my_luks2_header
588 /dev/plaintext_device
589 Initialize LUKS2 in-place encryption operation only and activate the
591 device (not yet encrypted):
592 cryptsetup reencrypt --encrypt --type luks2 --init-only
594 --reduce-device-size 32m /dev/plaintext_device my_future_luks_device
595 Resume online encryption on device initialized in example above:
597 cryptsetup reencrypt --resume-only /dev/plaintext_device or cryptsetup
599 reencrypt --active-name my_future_luks_device
600 LUKS2 REENCRYPTION EXAMPLES
602 Reencrypt LUKS2 device (refresh volume key only):
603 cryptsetup reencrypt /dev/encrypted_device
605 LUKS2 DECRYPTION EXAMPLES
607 Decrypt LUKS2 device with header put in head of data device (header
608 file does not exist):
609 cryptsetup reencrypt --decrypt --header /export/header/to/file
611 /dev/encrypted_device
612 Decrypt LUKS2 device with detached header (header file exists):
614 cryptsetup reencrypt --decrypt --header detached-luks2-header
616 /dev/encrypted_device
617 Resume interrupted LUKS2 decryption:
619 cryptsetup reencrypt --resume-only --header luks2-hdr-file
621 /dev/encrypted_device
622
624 Report bugs at cryptsetup mailing list <cryptsetup@lists.linux.dev> or
625 in Issues project section
626 <https://gitlab.com/cryptsetup/cryptsetup/-/issues/new>.
627 Please attach output of the failed command with --debug option added.
629
631 Cryptsetup FAQ
632 <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
633 cryptsetup(8), integritysetup(8) and veritysetup(8)
635
637 Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
638cryptsetup 2.5.0 2022-07-28 CRYPTSETUP-REENCRYPT(8)