cryptsetup/man/cryptsetup-reencrypt.8.adoc

= 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[]