cryptsetup-reencrypt

cryptsetup-reencrypt [OPTIONS] <device>
cryptsetup-reencrypt <device> --resume
cryptsetup-reencrypt <device> --cancel
cryptsetup-reencrypt <device> --status

--new-key-slot <NUM>
    Specifies a temporary key slot to use for the new key, typically an empty one.

--new-cipher <CIPHER[:MODE]>
    Defines the new cipher and optional mode to use for encryption (e.g., aes-xts-plain64).

--new-key-size <BITS>
    Sets the new key size in bits (e.g., 256).

--new-pbkdf <PBKDF>
    Specifies the new PBKDF (e.g., argon2i, pbkdf2) for key derivation.

--new-pbkdf-force-iterations <ITER>
    Forces the PBKDF iterations, bypassing internal benchmarks.

--header-only
    Re-encrypts only the LUKS header, not the data area.

--allow-discards
    Enables TRIM/DISCARD support for the re-encrypted blocks, potentially improving performance on SSDs.

--data-alignment <ALIGNMENT>
    Sets the sector alignment for the re-encryption process.

--reduce-device-size <SIZE>
    Reduces the effective size of the device during re-encryption.

--resume
    Continues a previously interrupted re-encryption operation.

--cancel
    Stops and rolls back a suspended re-encryption operation, restoring the original state.

--offline
    Performs re-encryption while the device is not opened by cryptsetup, requiring the volume to be unmounted.

--online
    Attempts to perform re-encryption while the device is opened and in use (for data only). Use with caution.

--progress-display <TYPE>
    Controls how progress is displayed (e.g., progressbar, percentage).

--use-random-key
    Uses a new random master key for the volume, discarding existing master key material.

The cryptsetup-reencrypt command provides a powerful and unique capability to re-encrypt an existing LUKS (Linux Unified Key Setup) encrypted volume without requiring the entire data to be decrypted and re-encrypted, or necessitating additional storage space for a new encrypted volume. This utility is invaluable for upgrading cryptographic parameters such as the encryption cipher, key size, or the PBKDF (Password-Based Key Derivation Function) used for key derivation, or for migrating a LUKS1 volume to the newer LUKS2 format. It works by streaming data in blocks, re-encrypting them on the fly and writing them back to the original location.

While not a truly "online" operation in the sense that the device can remain actively mounted and in use for all changes (especially header modifications), cryptsetup-reencrypt allows for a semi-online re-encryption process for data blocks, which can be paused and resumed. This minimizes downtime and simplifies the process compared to traditional methods involving data migration. It manages this complex task by utilizing a temporary key slot in the LUKS header to store the new encryption key and parameters during the re-encryption process. This ensures data integrity and allows for recovery in case of an interruption.

It's an essential tool for maintaining the security of encrypted storage over time, adapting to new cryptographic standards or improving security without a complete reformat and data restoration.

While designed for safety, cryptsetup-reencrypt is an inherently critical operation. It is strongly recommended to backup all critical data before proceeding.

A free LUKS key slot is required to store the temporary new header during the process. If all 8 key slots are in use, you must remove one first.

Interrupting the operation, especially during the header re-encryption phase, can potentially render the volume inaccessible. Although it has recovery mechanisms, unexpected power loss or system crashes are a risk.

The process can be time-consuming for large volumes and will impact system performance while running. For 'online' data re-encryption, the underlying filesystem and applications might experience reduced responsiveness.

Before starting, ensure the LUKS volume is unmounted if using --offline mode, or carefully consider the implications of --online mode. Provide the necessary password(s) when prompted.
1. Preparation: Ensure a free key slot is available. If not, remove an unused key slot first with cryptsetup luksKillSlot.
2. Execution: Run the command with desired parameters, e.g., cryptsetup-reencrypt --new-cipher aes-xts-plain64 --new-key-size 512 /dev/sdXN.
3. Monitoring: Monitor the progress using the --progress-display option.
4. Interruption/Resumption: If interrupted, the operation can usually be resumed using cryptsetup-reencrypt /dev/sdXN --resume. To revert to the original state, use cryptsetup-reencrypt /dev/sdXN --cancel.
5. Completion: Once complete, the temporary key slot is removed, and the volume operates with its new cryptographic parameters.

One of the most common and powerful uses of cryptsetup-reencrypt is to migrate an existing LUKS1 volume to the newer LUKS2 format. This is typically done by running the command with the --new-pbkdf argon2i option (as Argon2 is a LUKS2-specific KDF) or by explicitly setting other LUKS2-specific parameters. This process updates the on-disk format of the LUKS header, allowing access to LUKS2's advanced features like multiple key slots, JSON metadata, and more robust PBKDFs, without needing to re-encrypt the entire data area if no cipher/key-size change is desired.

The cryptsetup-reencrypt utility was introduced as part of the cryptsetup project starting with version 2.0.0. Its development was driven by the increasing need for in-place re-encryption capabilities, particularly with the introduction of the more flexible LUKS2 format and the desire to update cryptographic parameters without the laborious process of decrypting and then re-encrypting an entire disk. It significantly simplified the maintenance and security upgrades of LUKS-encrypted volumes, addressing a long-standing demand from users and administrators.

cryptsetup(8), luksformat(8)