Change a LUKS Passphrase Safely with cryptsetup

Someone left the company, and cryptsetup luksChangeKey is how you retire their passphrase without touching a byte of the encrypted data underneath. It swaps one existing LUKS passphrase for a new one while leaving the volume key unchanged.

This guide targets cryptsetup 2.7.0, supplied here by the cryptsetup-bin package version 2:2.7.0-1ubuntu4.2. Allow about ten minutes, plus the time needed for the passphrase derivation benchmark. This is a security-sensitive metadata change. You need root access, the LUKS device or a detached-header arrangement, the current passphrase, and a safe way to store the replacement. Do not start on the only copy of a critical disk without a tested header backup and a recovery plan.

1. Identify the exact device and version

First, confirm the command version and identify the LUKS device. These are read-only checks and do not need elevated privileges:

$ cryptsetup --version
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ lsblk -f
$ dpkg-query -W -f='${Package} ${Version}\n' cryptsetup-bin
cryptsetup-bin 2:2.7.0-1ubuntu4.2

Replace /dev/REPLACE_WITH_LUKS_DEVICE in the examples with the block device that lsblk -f shows as LUKS. Do not use a mounted filesystem path such as /home, and do not guess a partition from its size.

Checkpoint: write down the device path and, if the header is detached, the separate header path. A detached header is supplied with --header; it is not the encrypted data device.

2. Make a header backup before changing anything

A LUKS header contains the keyslot metadata needed to open the volume. Back it up to protected storage before changing a passphrase. This command changes no keyslot, but it does write a sensitive recovery file, so use elevated privileges and restrict the file afterwards:

# cryptsetup luksHeaderBackup /dev/REPLACE_WITH_LUKS_DEVICE \
    --header-backup-file /root/REPLACE_WITH_LUKS_DEVICE-luks-header.img
# chmod 600 /root/REPLACE_WITH_LUKS_DEVICE-luks-header.img

Keep the backup offline and protected like the passphrases. Anyone who obtains both the encrypted media and its header backup has more opportunity to attack the volume. The backup is not an undo button for unrelated disk writes, and restoring it later can discard legitimate keyslot changes.

3. Use the normal interactive change

The simplest and least error-prone form reads the old passphrase and the new passphrase from the terminal. Run it as root:

# cryptsetup luksChangeKey --verify-passphrase \
    /dev/REPLACE_WITH_LUKS_DEVICE
Enter passphrase to be changed:
Enter new passphrase:
Verify passphrase:

Without --key-slot, cryptsetup puts the new passphrase in a free keyslot when one is available, then removes the slot that held the old passphrase. If no free slot exists, it overwrites the old slot directly. LUKS2 avoids overwriting an existing keyslot area while enough free keyslot space remains, but a media failure during an overwrite can still make the container inaccessible. Do not interrupt power or remove the device during this operation.

4. Verify the new passphrase without opening the volume

Use a separate terminal after the change. The --test-passphrase option checks whether a passphrase works without activating a device mapping:

# cryptsetup --test-passphrase luksOpen \
    /dev/REPLACE_WITH_LUKS_DEVICE ignored-mapping
# printf 'exit status: %s\n' "$?"
exit status: 0

Enter the new passphrase when prompted. The mapping name is required by the luksOpen syntax, but --test-passphrase means no mapping is actually created. A status of 0 confirms the new passphrase works. If it fails, stop rather than repeatedly guessing: check that you used the intended device, header and passphrase.

Tip: to test the old passphrase, repeat the command and enter it. It should fail after a successful replacement, but do not treat that failure as proof until the new passphrase test has already returned status 0.

5. Change a particular keyslot when required

Use --key-slot only when you have inspected the layout and deliberately want to overwrite that slot. The supplied passphrase must belong to the selected slot:

# cryptsetup luksDump /dev/REPLACE_WITH_LUKS_DEVICE
# cryptsetup luksChangeKey --key-slot 2 --verify-passphrase \
    /dev/REPLACE_WITH_LUKS_DEVICE

For LUKS1, valid slots are 0 to 7. LUKS2 slot IDs can be 0 to 31, although the usable number depends on the keyslot area and key size. A slot number is not a passphrase: select the wrong one and the command either rejects a passphrase that belongs elsewhere, or you replace the wrong credential after supplying that slot's own passphrase.

If the device uses a detached header, include the same header option in every relevant command:

# cryptsetup luksChangeKey --header /dev/REPLACE_WITH_HEADER \
    --verify-passphrase /dev/REPLACE_WITH_DATA_DEVICE

6. Use key files only with deliberate byte handling

A key file can supply the old passphrase with --key-file. The new key file is the positional argument, which is an easy detail to reverse:

# cryptsetup luksChangeKey \
    --key-file /root/REPLACE_WITH_OLD_KEY \
    --new-keyfile-size 32 \
    /dev/REPLACE_WITH_LUKS_DEVICE \
    /root/REPLACE_WITH_NEW_KEY

Here, --key-file reads the existing passphrase and the final path supplies the replacement. --new-keyfile-size 32 limits the new input to 32 bytes, useful when the file has a known fixed length; it does not create or trim the file. Set permissions before use, avoid shell history containing secret values, and remove temporary copies using your organisation's secure handling procedure.

If the old key is read from standard input, use --key-file -. Reading from standard input does not stop at newline characters. The timeout option does not apply to key-file input, and --verify-passphrase is ignored for file or standard-input input. For an interactive change, keep verification enabled.

7. Recover from a failed or interrupted change

If the command rejects the old passphrase, check the device and detached-header path first. If it fails while writing keyslot metadata, do not keep retrying blindly: preserve the error output, check the device health, and use the header backup only with a clear recovery procedure, since restoring it may remove a passphrase added after the backup was made.

Recovery: there is no ordinary undo command for a passphrase replacement. The practical rollback is to run luksChangeKey again while you still have a working passphrase, changing it to a known replacement. If the volume no longer opens at all, stop writing to the device and involve whoever maintains your recovery process.

Done means