Skip to content

AN07: How to change the passphrase

Jump to bottom
Seiichi "Suikan" Horie edited this page Jul 22, 2021 · 15 revisions

Sometimes, users want to change the passphrase of the LUKS volume. The major reasons are :

In any way, changing the LUKS passphrase is tricky. This application note explains how to change the LUKS passphrase.

Prerequisite

  • The system was installed by Kaiten-Yaki.
  • Working in the booted system. Not the LiveCD system.
  • At least one vacant LUKS key slot.

The usage of the slot can be checked by the following command :

sudo cryptsetup luksDump /dev/sda1 | grep -i ABLED

For example :

takemasa@mate-vm:~$ sudo cryptsetup luksDump /dev/sda1 | grep -i ABLED
Key Slot 0: ENABLED
Key Slot 1: ENABLED
Key Slot 2: ENABLED
Key Slot 3: DISABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

In this example, slots 3-7 are vacant.

Changing user passphrase

The user passphrase is the one that the user types during the boot. To change the user passphrase, follow the procedure :

  1. Add a temporary passphrase.
  2. Identify the key slot of the existing user passphrase.
  3. Kill the key slot of the existing user passphrase.
  4. Add a user passphrase.
  5. Delete the temporary passphrase.

The temporary passphrase is redundant. You can change the passphrase without it. For example, you can use cryptsetup luksConvert to change the key directory. But a media failure during the conversion makes your system un-bootable. The procedure with the temporary passphrase reduces this risk.

Add temporary passphrase

Use cryptsetup to add a temporary passphrase. Any easy passphrase is OK. For example "foo".

sudo cryptsetup luksAddKey /dev/sdXN

Where X is a device-identifying string like A, B, C... Also where N is numbers like 1, 2, 3. The device name depends on the system. Check your device name first.

Next, confirm the temporary passphrase is correctly set or not. The following command asks you to type the passphrase, and then, display which slot is matched.

sudo cryptsetup luksOpen -v --test-passphrase /dev/sdXN

Following is an example of adding a temporary passphrase and confirmation. The temporary passphrase is set to the key slot 3.

takemasa@mate-vm:~$ sudo cryptsetup luksAddKey /dev/sda1
Enter any existing passphrase: 
Enter new passphrase for key slot: 
Verify passphrase: 
takemasa@mate-vm:~$ sudo cryptsetup luksDump /dev/sda1 | grep -i ABLED
Key Slot 0: ENABLED
Key Slot 1: ENABLED
Key Slot 2: ENABLED
Key Slot 3: ENABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED
takemasa@mate-vm:~$ sudo cryptsetup luksOpen -v --test-passphrase /dev/sda1
Enter passphrase for /dev/sda1: 
Key slot 3 unlocked.
Command successful.
takemasa@mate-vm:~$

Identify the key slot of the existing user passphrase

After adding a temporary passphrase, identify the slot that contains the current user passphrase.

Run the following command and type user passphrase when the command prompts. After a successful run, the command displays the corresponding key slot for the passphrase.

sudo cryptsetup luksOpen -v --test-passphrase /dev/sdXN

The following is an example. We can see the given passphrase of the LUKS volume on /dev/sda1 is stored in the key slot 0.

takemasa@mate-vm:~$ sudo cryptsetup luksOpen -v --test-passphrase /dev/sda1
Enter passphrase for /dev/sda1: 
Key slot 0 unlocked.
Command successful.

Kill the key slot of the existing user passphrase

Now, it's time to delete the key slot of the current passphrase. Run the cryptsetup luksKillSlot.

Note: To delete the key slot, cryptsetup prompts to input some passphrase which is not going to be delete. Type the temporary passphrase here.

sudo cryptsetup luksKillSlot /dev/sdXN <slot-to-delete>

Where <slot-to-delete> is the key slot number that we identify above.

The following is an example. We can see slot 0 is DISABLED, now.

takemasa@mate-vm:~$ sudo cryptsetup luksKillSlot /dev/sda1 0
Enter any remaining passphrase: 
takemasa@mate-vm:~$ sudo cryptsetup luksDump /dev/sda1 | grep -i ABLED
Key Slot 0: DISABLED
Key Slot 1: ENABLED
Key Slot 2: ENABLED
Key Slot 3: ENABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

Add a user passphrase

Finally, we can add a new user passphrase by cryptset luksAddKey command.

sudo cryptsetup luksAddKey --iter-time=<duration> /dev/sdXN

Where <duration> is the time of the hash calculation. The unit is a millisecond. See AN03 for details.

The following is an example. We can see the new passphrase is added to the key slot 0.

takemasa@mate-vm:~$ sudo cryptsetup luksAddKey --iter-time=50 /dev/sda1
Enter any existing passphrase: 
Enter new passphrase for key slot: 
Verify passphrase: 
takemasa@mate-vm:~$ sudo cryptsetup luksOpen -v --test-passphrase /dev/sda1
Enter passphrase for /dev/sda1: 
Key slot 0 unlocked.
Command successful.

Delete the temporary passphrase

Once the new passphrase is stored in a key slot correctly, We don't need the temporary passphrase anymore. In the following example, we identify where the temporary passphrase is stored, and then delete that key slot. Be sure to type temporary passphrase, if prompted.

takemasa@mate-vm:~$ sudo cryptsetup luksOpen -v --test-passphrase /dev/sda1
Enter passphrase for /dev/sda1: 
Key slot 3 unlocked.
Command successful.
takemasa@mate-vm:~$ sudo cryptsetup luksKillSlot /dev/sda1 3
Enter any remaining passphrase: 
takemasa@mate-vm:~$

Now, everything is done. You can boot the system with a new user passphrase and the new duration.

Changing kernel passphrase.

If a system is installed by Kaiten-yaki, each root volume has a unique random binary key in the /etc/luks/boot_os.keyfile. From the viewpoint of security, usually, you don't need to change this key because that is enough strong compared to the user passphrase.

The possible motivation of the changing passphrase is --iter-time parameter to shorten the duration at mistyping of the user passphrase. See AN03 for details.

In this section, we assume:

  • A user who wants to change --iter-time parameter of the cryptsetup command.
  • random key value is kept as the original value.

The steps of the procedure are:

  1. Identify the key slot number which is assigned to the specific key file.
  2. Add that key file with the new --iter-time parameter.
  3. Delete the original key slot.

Note: You have to do the following procedure on the Linux system you want to change. For example, if you want to change the 2nd Linux installation in your system, you have to start that 2nd Linux and then, do the procedure.

Identify the key slot number which is assigned to the specific key file

First of all, you must identify which key slot is occupied by the key in the keyfile of the Linux installation. This can be done with the following command.

sudo cryptsetup luksOpen -v --test-passphrase /dev/sdXN -d /etc/luks/boot_os.keyfile

Where X is a, b, c, ... Also where N is 1, 2, 3... The device name depends on the system. Check your device name at first.

The Followings are an example, we can see the key slot 2 is occupied by a value in the keyfile.

takemasa@mate-vm:~$ sudo cryptsetup luksOpen -v --test-passphrase /dev/sda1 -d /etc/luks/boot_os.keyfile
Key slot 2 unlocked.
Command successful.

Add that key file with the new --iter-time parameter

Next, add the key in the keyfile with the new iter-time parameter. You can do it by the cryptsetup luksAddKey command.

sudo cryptsetup luksAddKey --iter-time=<duration> /dev/sdXN /etc/luks/boot_os.keyfile

Where <duration> is the time of the hash calculation. The unit is a millisecond. See AN03 for details.

The following is an example. We can see the key is added to key slot 3.

takemasa@mate-vm:~$ sudo cryptsetup luksDump /dev/sda1 | grep -i ABLED
Key Slot 0: ENABLED
Key Slot 1: ENABLED
Key Slot 2: ENABLED
Key Slot 3: DISABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED
takemasa@mate-vm:~$ sudo cryptsetup luksAddKey --iter-time=50 /dev/sda1 /etc/luks/boot_os.keyfile
Enter any existing passphrase: 
takemasa@mate-vm:~$ sudo cryptsetup luksDump /dev/sda1 | grep -i ABLED
Key Slot 0: ENABLED
Key Slot 1: ENABLED
Key Slot 2: ENABLED
Key Slot 3: ENABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

Delete the original key slot

At last, we can delete the key slot occupied by the old key.

sudo cryptsetup luksKillSlot /dev/sdXN <slot-to-delete>

Where <slot-to-delete> is the one we identified above as occupied by the old key.

The following is an example. We can see the key slot 2 is deleted.

takemasa@mate-vm:~$ sudo cryptsetup luksKillSlot /dev/sda1 2
Enter any remaining passphrase: 
takemasa@mate-vm:~$ sudo cryptsetup luksDump /dev/sda1 | grep -i ABLED
Key Slot 0: ENABLED
Key Slot 1: ENABLED
Key Slot 2: DISABLED
Key Slot 3: ENABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

Conclusion

While the above procedures have been tested, the LUKS key manipulation is dangerous. If possible, keep using the working system, without modification.

Clone this wiki locally