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

NAME

6       cryptsetup-reencrypt - reencrypt LUKS encrypted volumes in-place
7

SYNOPSIS

9       cryptsetup reencrypt [<options>] <device> or --active-name <name>
10       [<new_name>]
11

DESCRIPTION

13       Run LUKS device reencryption.
14
15       There are 3 basic modes of operation:
16
17       •   device reencryption (reencrypt)
18
19       •   device encryption (reencrypt --encrypt/--new/-N)
20
21       •   device decryption (reencrypt --decrypt)
22
23       <device> or --active-name <name> (LUKS2 only) is mandatory parameter.
24
25       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
30       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
34       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
38       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
43       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
47       ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS ACTION ON
48       LUKS DEVICE.
49
50       <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

LUKS2 REENCRYPTION

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
66       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
73       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
78       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

LUKS1 REENCRYPTION

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
90       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

OPTIONS

95       --block-size value (LUKS1 only)
96           Use re-encryption block size of value in MiB.
97
98           Values can be between 1 and 64 MiB.
99
100       --use-directio (LUKS1 only)
101           Use direct-io (O_DIRECT) for all read/write data operations related
102           to block device undergoing reencryption.
103
104           Useful if direct-io operations perform better than normal buffered
105           operations (e.g. in virtual environments).
106
107       --use-fsync (LUKS1 only)
108           Use fsync call after every written block. This applies for
109           reencryption log files as well.
110
111       --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
116       --type <device-type>
117           Specifies required (encryption mode) or expected (other modes) LUKS
118           format. Accepts only luks1 or luks2.
119
120       --hash, -h <hash-spec>
121           LUKS1: Specifies the hash used in the LUKS1 key setup scheme and
122           volume key digest.
123
124           NOTE: if this parameter is not specified, default hash algorithm is
125           always used for new LUKS1 device header.
126
127           LUKS2: Ignored unless new keyslot pbkdf algorithm is set to PBKDF2
128           (see --pbkdf).
129
130       --cipher, -c <cipher-spec>
131           LUKS2: Set the cipher specification string for data segment only.
132
133           LUKS1: Set the cipher specification string for data segment and
134           keyslots.
135
136           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
142           cryptsetup --help shows the compiled-in defaults.
143
144           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
148           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
152       --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
157       --key-file, -d name
158           Read the passphrase from file.
159
160           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
163           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
168           If this option is not used, cryptsetup will ask for all active
169           keyslot passphrases.
170
171       --keyfile-offset value
172           Skip value bytes at the beginning of the key file.
173
174       --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
180           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
184       --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
191       --use-random, --use-urandom
192           Define which kernel random number generator will be used to create
193           the volume key.
194
195       --keep-key
196           LUKS2: Do not change effective volume key and change other
197           parameters provided it is requested.
198
199           LUKS1: Reencrypt only the LUKS1 header and keyslots. Skips data
200           in-place reencryption.
201
202       --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
206           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
210           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
215       --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
219           See /proc/crypto for more information. Note that key-size in
220           /proc/crypto is stated in bytes.
221
222           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
226           If there is not enough space for keyslots with new key size, you
227           can destructively shrink device with --reduce-device-size option.
228
229       --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
233           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
237       --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
242           WARNING: This is destructive operation. Data beyond --device-size
243           limit may be lost after operation gets finished.
244
245           If no unit suffix is specified, the size is in bytes.
246
247           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
251       --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
257           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
261           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
265           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
270           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
277           You can see all PBKDF parameters for particular LUKS2 keyslot with
278           cryptsetup-luksDump(8) command.
279
280           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
287           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
298       --iter-time, -i <number of milliseconds>
299           The number of milliseconds to spend with PBKDF passphrase
300           processing for the new LUKS header.
301
302       --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
308       --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
313       --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
318       --progress-frequency seconds
319           Print separate line every seconds with reencryption progress.
320
321       --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
327               {
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
336           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
340       --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
345           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
349       --tries, -T
350           How often the input of the passphrase shall be retried. The default
351           is 3 tries.
352
353       --align-payload <number of 512 byte sectors>
354           Align payload at a boundary of value 512-byte sectors.
355
356           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
362           For a detached LUKS header, this option specifies the offset on the
363           data device. See also the --header option.
364
365           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
370       --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
374           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
378           The UUID must be provided in the standard UUID format, e.g.
379           12345678-1234-1234-1234-123456789abc.
380
381       --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
386           If used with --encrypt/--new option, the header file will be
387           created (or overwritten). Use with care.
388
389           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
396           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
399       --force-offline-reencrypt (LUKS2 only)
400           Bypass active device auto-detection and enforce offline
401           reencryption.
402
403           This option is useful especially for reencryption of LUKS2 images
404           put in files (auto-detection is not reliable in this scenario).
405
406           It may also help in case active device auto-detection on particular
407           data device does not work or report errors.
408
409           WARNING: Use with extreme caution! This may destroy data if the
410           device is activated and/or actively used.
411
412       --force-password
413           Do not use password quality checking for new LUKS passwords.
414
415           This option is ignored if cryptsetup is built without password
416           quality checking support.
417
418           For more info about password quality check, see the manual page for
419           pwquality.conf(5) and passwdqc.conf(5).
420
421       --disable-locks
422           Disable lock protection for metadata on disk. This option is valid
423           only for LUKS2 and ignored for other formats.
424
425           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
429           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
433       --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
438       --sector-size bytes (LUKS2 only)
439           Reencrypt device with new encryption sector size enforced.
440
441           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
445       --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
451       --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
459       --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
465       --keyslot-cipher <cipher-spec>
466           This option can be used to set specific cipher encryption for the
467           LUKS2 keyslot area.
468
469       --keyslot-key-size <bits>
470           This option can be used to set specific key size for the LUKS2
471           keyslot area.
472
473       --encrypt, --new, -N
474           Initialize (and run) device in-place encryption mode.
475
476       --decrypt
477           Initialize (and run) device decryption mode.
478
479       --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
484       --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
491       --resilience mode (LUKS2 only)
492           Reencryption resilience mode can be one of checksum, journal or
493           none.
494
495           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
500           journal: the hotzone is journaled in the binary area (so the data
501           are written twice).
502
503           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
507           Resilience modes can be changed unless datashift mode is used for
508           operation initialization (encryption with --reduce-device-size
509           option)
510
511       --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
516       --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
523           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
527       --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
532           It could be useful if you added some space to underlying partition
533           or logical volume (so last size sectors contains no data).
534
535           For units suffix see --device-size parameter description.
536
537           WARNING: This is a destructive operation and cannot be reverted.
538           Use with extreme care - accidentally overwritten filesystems are
539           usually unrecoverable.
540
541           LUKS2: Initialize LUKS2 reencryption with data device size
542           reduction (currently only encryption mode is supported).
543
544           Recommended minimal size is twice the default LUKS2 header size
545           (--reduce-device-size 32M) for encryption mode.
546
547           LUKS1: Enlarge data offset to specified value by shrinking device
548           size.
549
550           You cannot shrink device more than by 64 MiB (131072 sectors).
551
552       --batch-mode, -q
553           Suppresses all confirmation questions. Use with care!
554
555           If the --verify-passphrase option is not specified, this option
556           also switches off the passphrase verification.
557
558       --debug or --debug-json
559           Run in debug mode with full diagnostic logs. Debug output lines are
560           always prefixed by #.
561
562           If --debug-json is used, additional LUKS2 JSON data structures are
563           printed.
564
565       --version, -V
566           Show the program version.
567
568       --usage
569           Show short option help.
570
571       --help, -?
572           Show help text and default parameters.
573

EXAMPLES

575       NOTE: You may drop --type luks2 option as long as LUKS2 format is
576       default.
577
578   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
582       cryptsetup reencrypt --encrypt --type luks2 --reduce-device-size 32m
583       /dev/plaintext_device
584
585       Encrypt LUKS2 device (in-place) with detached header put in a file:
586
587       cryptsetup reencrypt --encrypt --type luks2 --header my_luks2_header
588       /dev/plaintext_device
589
590       Initialize LUKS2 in-place encryption operation only and activate the
591       device (not yet encrypted):
592
593       cryptsetup reencrypt --encrypt --type luks2 --init-only
594       --reduce-device-size 32m /dev/plaintext_device my_future_luks_device
595
596       Resume online encryption on device initialized in example above:
597
598       cryptsetup reencrypt --resume-only /dev/plaintext_device or cryptsetup
599       reencrypt --active-name my_future_luks_device
600
601   LUKS2 REENCRYPTION EXAMPLES
602       Reencrypt LUKS2 device (refresh volume key only):
603
604       cryptsetup reencrypt /dev/encrypted_device
605
606   LUKS2 DECRYPTION EXAMPLES
607       Decrypt LUKS2 device with header put in head of data device (header
608       file does not exist):
609
610       cryptsetup reencrypt --decrypt --header /export/header/to/file
611       /dev/encrypted_device
612
613       Decrypt LUKS2 device with detached header (header file exists):
614
615       cryptsetup reencrypt --decrypt --header detached-luks2-header
616       /dev/encrypted_device
617
618       Resume interrupted LUKS2 decryption:
619
620       cryptsetup reencrypt --resume-only --header luks2-hdr-file
621       /dev/encrypted_device
622

REPORTING BUGS

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
628       Please attach output of the failed command with --debug option added.
629

SEE ALSO

631       Cryptsetup FAQ
632       <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
633
634       cryptsetup(8), integritysetup(8) and veritysetup(8)
635

CRYPTSETUP

637       Part of cryptsetup project <https://gitlab.com/cryptsetup/cryptsetup/>.
638
639
640
641cryptsetup 2.6.1                  2023-07-19           CRYPTSETUP-REENCRYPT(8)
Impressum