1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
= cryptsetup-reencrypt(8)
:doctype: manpage
:manmanual: Maintenance Commands
:mansource: cryptsetup {release-version}
:man-linkstyle: pass:[blue R < >]
:COMMON_OPTIONS:
:ACTION_REENCRYPT:
== Name
cryptsetup-reencrypt - reencrypt LUKS encrypted volumes in-place
== SYNOPSIS
*cryptsetup _reencrypt_ [<options>] <device> or --active-name <name> [<new_name>]*
== DESCRIPTION
Run LUKS device reencryption.
There are 3 basic modes of operation:
* device reencryption (_reencrypt_)
* device encryption (_reencrypt_ --encrypt/--new/-N)
* device decryption (_reencrypt_ --decrypt)
<device> or --active-name <name> (LUKS2 only) is mandatory parameter.
Cryptsetup _reencrypt_ action can be used to change reencryption parameters, which otherwise require full on-disk data change (re-encryption).
The _reencrypt_ action reencrypts data on the LUKS device in-place.
You can regenerate *volume key* (the real key used in on-disk encryption unlocked by passphrase), *cipher*, *cipher mode* or *encryption sector size* (LUKS2 only).
If you need to use both luksChangeKey and reencrypt (e.g., to recover from a leak), you need to use them in that order to avoid leaking the new volume key.
The reencryption process may be safely interrupted by a user via SIGINT signal (ctrl+c).
The same applies to the SIGTERM signal (i.e., issued by systemd during system shutdown).
For in-place encryption mode, the _reencrypt_ action additionally takes all options available for the _luksFormat_ action for the respective LUKS version (see cryptsetup-luksFormat man page for more details).
See *cryptsetup-luksFormat*(8).
Note that for encrypt and decrypt mode, the whole device must be treated as unencrypted -- there are no guarantees of confidentiality as part of the device contains plaintext.
*ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS ACTION ON LUKS DEVICE.*
*<options>* can be [--batch-mode,
--block-size,
--cipher,
--debug,
--debug-json,
--decrypt,
--device-size,
--disable-locks,
--encrypt,
--force-offline-reencrypt,
--hash,
--header,
--hotzone-size,
--iter-time,
--init-only,
--keep-key,
--key-file,
--key-size,
--key-slot,
--keyfile-offset,
--keyfile-size,
--tries,
--timeout,
--pbkdf,
--pbkdf-force-iterations,
--pbkdf-memory,
--pbkdf-parallel,
--progress-frequency,
--progress-json,
--reduce-device-size,
--resilience,
--resilience-hash,
--resume-only,
--sector-size,
--use-directio,
--use-random,
--use-urandom,
--use-fsync,
--uuid,
--verbose,
--volume-key-file,
--write-log].
== LUKS2 REENCRYPTION
With the <device> parameter, cryptsetup looks up the active <device> dm mapping.
If no active mapping is detected, it starts offline LUKS2 reencryption; otherwise, online reencryption occurs.
To resume already initialized or interrupted reencryption, just run the cryptsetup _reencrypt_ command again to continue the reencryption operation.
Reencryption may be resumed with different --resilience or --hotzone-size unless implicit datashift resilience mode is used: either encrypt mode with --reduce-device-size option or decrypt mode with original LUKS2 header exported in --header file.
If the reencryption process was interrupted abruptly (reencryption process crash, system crash, or power off), it may require recovery.
The recovery is run automatically on next activation (action _open_) when needed or explicitly by the user (action _repair_).
The optional parameter <new_name> takes effect only with the encrypt option, and it activates device <new_name> immediately after encryption initialization is finished.
That's useful when the device needs to be ready as soon as possible and mounted (used) before full data area encryption is completed.
== LUKS1 REENCRYPTION
The current working directory must be writable, and temporary files created during reencryption must be present.
During reencryption, the LUKS1 device is marked unavailable and must be offline (no dm-crypt mapping or mounted filesystem).
*WARNING*: The LUKS1 reencryption code is not resistant to hardware or kernel failures during reencryption (you can lose your data in this case).
include::man/common_options.adoc[]
== EXAMPLES
You may drop *--type luks2* option as long as LUKS2 format is default.
=== LUKS2 ENCRYPTION EXAMPLES
Encrypt LUKS2 device (in-place).
Make sure the last 32 MiB on _/dev/plaintext_ is unused (e.g., does not contain filesystem data):
*cryptsetup reencrypt --encrypt --type luks2 --reduce-device-size 32m /dev/plaintext_device*
Encrypt LUKS2 device (in-place).
Only the initial 1 GiB of original _/dev/plaintext_ data is encrypted while being shifted backwards.
Make sure the last 32 MiB (tail) on the data device is unused (e.g., does not contain any data):
*cryptsetup reencrypt --encrypt --type luks2 --device-size 1g --reduce-device-size 32m /dev/plaintext_device*
Encrypt LUKS2 device (in-place) with detached header, put in a file:
*cryptsetup reencrypt --encrypt --type luks2 --header my_luks2_header /dev/plaintext_device*
Initialize LUKS2 in-place encryption operation only and activate the device (not yet encrypted):
*cryptsetup reencrypt --encrypt --type luks2 --init-only --reduce-device-size 32m /dev/plaintext_device my_future_luks_device*
Resume online encryption on the device initialized in the example above:
*cryptsetup reencrypt --resume-only /dev/plaintext_device* or
*cryptsetup reencrypt --active-name my_future_luks_device*
=== LUKS2 REENCRYPTION EXAMPLES
Reencrypt LUKS2 device (refresh volume key only):
*cryptsetup reencrypt /dev/encrypted_device*
Reencrypt LUKS2 device using keyslot(s) associated with the token 3.
All other keyslots will be removed after the reencryption finishes.
*cryptsetup reencrypt --token-id 3 /dev/encrypted_device*
Reencrypt LUKS2 device using keyslots associated with all 'systemd-tpm2' tokens.
All other keyslots will be removed after the reencryption finishes.
*cryptsetup reencrypt --token-type systemd-tpm2 /dev/encrypted_device*
=== LUKS2 DECRYPTION EXAMPLES
Decrypt LUKS2 device with header put in the head of the data device (header file does not exist):
*cryptsetup reencrypt --decrypt --header /export/header/to/file /dev/encrypted_device*
Decrypt LUKS2 device with detached header (header file exists):
*cryptsetup reencrypt --decrypt --header detached-luks2-header /dev/encrypted_device*
Resume interrupted LUKS2 decryption:
*cryptsetup reencrypt --resume-only --header luks2-hdr-file /dev/encrypted_device*
include::man/common_footer.adoc[]
|
