Changing the LUKS passphrase

general / published / guide #17 / ≈ 3 min read

If you installed Linux with "full-disk encryption," then somewhere on your hard drive is a LUKS-encrypted partition. LUKS (Linux Unified Key Setup) is the standard way Linux encrypts disks. The password you typed at install time is what unlocks the drive at every boot — and at some point you'll probably want to change it.

The key concept: LUKS doesn't store your password. It stores a master key, encrypted by your password. There can be up to 8 (LUKS1) or 32 (LUKS2) different passwords that unlock the same master key — each one lives in a numbered slot.

The safe way to change a password is to add a new one first, test it works, then remove the old one. If you make a typo on the new password, the old one still works — no lock-out.

Step 1: Find your encrypted partition

lsblk -f

Look for a row where FSTYPE is crypto_LUKS. The name on the left (e.g. sda3) is what you want. Make a note of /dev/sda3 (substitute the right name in everything below).

You can confirm with:

sudo cryptsetup luksDump /dev/sda3

This shows the LUKS version and which key slots are currently in use. On a fresh install only slot 0 is filled.

Step 2: Add a new password

sudo cryptsetup luksAddKey /dev/sda3

You'll be prompted twice:

  1. First for an existing passphrase — this unlocks the master key.
  2. Then for the new passphrase, twice (to catch typos).

If everything worked, the dump will now show two slots in use:

sudo cryptsetup luksDump /dev/sda3 | grep Keyslot

Step 3: Test the new password before deleting the old

The cleanest test is to reboot and unlock the disk with only the new password. If you'd rather not reboot:

sudo cryptsetup open --test-passphrase /dev/sda3 && echo OK

When prompted, enter only the new passphrase. If you see OK, it works.

Step 4: Remove the old password

sudo cryptsetup luksRemoveKey /dev/sda3

It'll ask which passphrase to remove — enter the old one. Done.

If you forgot the old passphrase but know which numbered slot it's in, kill the slot by number instead:

sudo cryptsetup luksKillSlot /dev/sda3 0

You'll be prompted for any remaining valid passphrase to authorise the kill.

The faster (riskier) way

If you're absolutely sure of the current passphrase and don't want the add-test-remove dance:

sudo cryptsetup luksChangeKey /dev/sda3

This swaps a key in place. The risk: if you mistype the new password twice (it happens), and that was your only key, you're locked out. Use the safe flow on the machine you can't afford to brick.

Always back up the header

The LUKS header at the start of the partition holds the encrypted master key and the slot metadata. A corrupted header makes the data unrecoverable, even if you remember the passphrase. Before any heavy editing:

sudo cryptsetup luksHeaderBackup /dev/sda3 
     --header-backup-file ~/luks-header-$(date +%F).bin
chmod 600 ~/luks-header-*.bin

Keep this file somewhere safe and offline. Anyone with the header file plus any valid passphrase can decrypt your disk — treat it like the encryption keys themselves.

Restore (you rarely need to):

sudo cryptsetup luksHeaderRestore /dev/sda3 
     --header-backup-file ~/luks-header-2026-05-14.bin

FreeBSD users: the equivalent is GELI

FreeBSD doesn't use LUKS; it uses GELI. Same idea (multiple keys, change without re-encrypting), different commands:

geli setkey -n 1 /dev/ada0p3        # set/replace key in slot 1
geli delkey -n 0 /dev/ada0p3        # remove key in slot 0

← back to index