Sharing a LUKS volume with someone else, or just want a spare credential before you forget the first one? cryptsetup luksAddKey adds a new passphrase to an existing device without touching the old one or re-encrypting any data.
You will add the new passphrase, confirm a fresh keyslot appeared, and test the new credential before you rely on it. The examples use cryptsetup 2.7.0 from the Ubuntu cryptsetup-bin package installed on this machine. Allow about fifteen minutes, plus the time needed to make and safely store a header backup. This is a metadata-changing operation: it does not re-encrypt the data, but it does write the LUKS header and keyslot area. You need the device path, an existing working passphrase, a new passphrase, and enough access to read and write the block device. The mutating commands normally need sudo.
Use the real LUKS device path in place of /dev/DEVICE. Do not guess from a mount point or copy a path from another host. A whole partition such as /dev/nvme0n1p3 or a LUKS container on a disk may be the correct device; the command must target the device that stores the LUKS header.
$ DEVICE=/dev/DEVICE
$ sudo cryptsetup luksDump "$DEVICE"Checkpoint: the command should print LUKS metadata and a list of keyslots. It reads the header and does not add or remove a key. If it says the device is not a valid LUKS device, stop and check the path rather than trying another destructive action.
Before changing keyslots, write a binary header backup to protected storage. Choose a destination that is not on the same failing disk, and restrict its permissions afterwards:
$ sudo cryptsetup luksHeaderBackup --header-backup-file /secure/backup/DEVICE-luks-header.img "$DEVICE"
$ sudo chmod 600 /secure/backup/DEVICE-luks-header.imgExpected result: cryptsetup returns to the shell without an error and the backup file exists. Check it without printing its contents:
$ sudo stat --printf='%n %s bytes\n' /secure/backup/DEVICE-luks-header.imgTreat this file as highly sensitive. A header backup together with a passphrase that was valid when the backup was made can decrypt the data even after that passphrase is removed from the live device. Keep it offline and protected. This backup is a recovery aid, not a harmless copy.
Run the normal form as an administrator:
$ sudo cryptsetup luksAddKey "$DEVICE"Cryptsetup asks first for an existing passphrase, then for the new one. Enter the existing passphrase when prompted. It only asks for the new one twice if you add --verify-passphrase, which makes the intended check explicit:
$ sudo cryptsetup --verify-passphrase luksAddKey "$DEVICE"Warning: do not add --batch-mode to an interactive operation casually. It suppresses confirmation questions and, without passphrase verification, also disables verification of the new interactive passphrase. Do not use --force-password merely to bypass a quality warning unless your password policy has been reviewed.
Inspect the header again:
$ sudo cryptsetup luksDump "$DEVICE"Compare the keyslot list with the output from step 1. One additional slot should be active or enabled. The exact slot number depends on which slots were already occupied, so do not write a script that assumes a particular number. LUKS1 has up to eight keyslots; LUKS2 can address slot IDs 0 through 31, although the number actually available depends on the header's keyslot area.
This inspection confirms a header change, not that you typed the intended new passphrase. The stronger check is to use the new passphrase through the same activation mechanism the machine normally uses. If the device is already open, do not close a production mapping solely to experiment: test during a maintenance window or on a safe copy where you can follow the normal activation procedure.
For unattended or precisely controlled workflows, the new passphrase can come from a file. The existing passphrase still belongs to --key-file; the new one belongs to --new-keyfile:
$ sudo cryptsetup --key-file /secure/old-passphrase \
--new-keyfile /secure/new-passphrase \
luksAddKey "$DEVICE"The file contents are read as passphrase data. File input skips interactive verification, and a newline is data unless you limit the read with --new-keyfile-size. Keep these files outside shared directories, set restrictive permissions, and remove temporary copies using your organisation's secure handling procedure after the operation. Do not put a passphrase directly in the command line: it can be exposed through shell history or process inspection.
A common trap is reversing the two inputs. --key-file authenticates an existing keyslot; it does not set the new passphrase. The positional file argument is an alternative way to supply the new passphrase, but --new-keyfile makes the role clearer in a reviewed command.
Normally, let cryptsetup choose the first free slot. If your recovery procedure requires a specific slot, use --new-key-slot:
$ sudo cryptsetup --new-key-slot 5 luksAddKey "$DEVICE"This fails if slot 5 is unavailable or unsuitable. Do not force a slot simply to make inventory look tidy. On LUKS2, per-keyslot PBKDF settings may differ; on LUKS1, the PBKDF type and hash are shared across keyslots. Leave cryptsetup's measured defaults alone unless you have a documented performance and recovery requirement.
If the new credential is confirmed, remove an old passphrase with the separate luksRemoveKey action:
$ sudo cryptsetup luksRemoveKey "$DEVICE"It asks for the passphrase to remove. This is another header change and is not an undo for a failed addition. Never remove the last usable passphrase. If you accidentally remove the wrong one, stop and use the header backup recovery plan rather than repeatedly guessing: a backup can restore an earlier keyslot state, but restoring it may also discard legitimate changes made since, so involve whoever owns the encrypted data.
cryptsetup luksDump "$DEVICE" identifies the expected LUKS header and shows the new keyslot.