= cryptsetup-luksChangeKey(8)
:doctype: manpage
:manmanual: Maintenance Commands
:mansource: cryptsetup {release-version}
:man-linkstyle: pass:[blue R < >]
:COMMON_OPTIONS:
:ACTION_LUKSCHANGEKEY:

== Name

cryptsetup-luksChangeKey - change an existing passphrase

== SYNOPSIS

*cryptsetup _luksChangeKey_ [<options>] <device> [<new key file>]*

== DESCRIPTION

Changes an existing passphrase.
The passphrase to be changed must be supplied interactively or via --key-file.
The new passphrase can be supplied interactively or in a file given as the positional argument.

If a keyslot is specified (via --key-slot), the passphrase for that keyslot must be given, and the new passphrase will overwrite the specified keyslot.
If no keyslot is specified and there is still a free keyslot, then the new passphrase will be put into a free keyslot before the keyslot containing the old passphrase is purged.
If there is no free keyslot, then the keyslot with the old passphrase is overwritten directly.

*WARNING:* If a keyslot is overwritten, a media failure during this operation can cause the overwrite to fail after the old passphrase has been wiped, making the LUKS container inaccessible.
LUKS2 mitigates that by never overwriting the existing keyslot area as long as there's a free space in the keyslots area at least for one more LUKS2 keyslot.

If you need to use both luksChangeKey and reencrypt (e.g., to recover from a key leak), you need to use them in that order to avoid leaking the new volume key.

Some parameters are effective only if used with the LUKS2 format that supports per-keyslot parameters.
For LUKS1, the PBKDF type and hash algorithm are always the same for all keyslots.

*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --new-keyfile-offset, --iter-time, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --new-keyfile-size, --key-slot, --force-password, --hash, --header, --disable-locks, --type, --keyslot-cipher, --keyslot-key-size, --timeout, --verify-passphrase].

include::man/common_options.adoc[]
include::man/common_footer.adoc[]