10 Linux cryptsetup Examples for LUKS Key Management (How to Add, Remove, Change, Reset LUKS encryption Key)

LUKS is the disk encryption for Linux.

First time when you encrypt a partition with LUKS (or when you select encrypt disk option during OS installation), you have to specify a password that will be used when you open the LUKS partition.

But, after that, you can mount and unmount the partition as many times as you like without having to enter the password until you reboot the system.

Imagine the following two scenarios:

1. You forgot the LUKS password. Or, you inherited a system from someone that has a mounted partition with LUKS encryption. You don’t have LUKS password for this. When you reboot the system, you’ll be in trouble, as you don’t have the LUKS key.
2. For security compliance purpose, you are required to change the LUKS encryption password frequently. In this case you have to rotate the LUKS key without disrupting the mounted partition.

In this tutorial, we’ll discuss everything that you need to know about LUKS key management.

1. Eight LUKS Key Slots

In LUKS, for a single encrypted partition, you can have eight different keys.

Any one of the eight different keys can be used to open the encrypted partition.

You can choose to have only one key on a partition, or you can assign all eight different keys.

These keys are stored in LUKS key slots for the partition. So, there will be 8 key slots for a partition.

To view all key slots, use cryptsetup luksDump as shown below. In this example, it is using only two slots.

# cryptsetup luksDump /dev/sdb1 | grep Slot
Key Slot 0: ENABLED
Key Slot 1: ENABLED
Key Slot 2: DISABLED
Key Slot 3: DISABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

In the above:

• /dev/sdb1 is the LUKS encrypted partition.
• Key Slot number starts from 0. Since we have 8 slots, key slot number starts from 0 through 7.
• ENABLED indicates that this particular slot has a key assigned to it.
• Here we have two slots with LUKS key. So, /dev/sdb1 LUKS encrypted partition has two keys assigned.

2. Add New LUKS Key

To add a new LUKS passphrase (LUKS key) to the /dev/sdb1 LUKS encrypted partition, use cryptsetup luksAddKey command as shown below.

# cryptsetup luksAddKey /dev/sdb1
Enter any passphrase: 
Enter new passphrase for key slot: 
Verify passphrase: 

In the above:

• When it says “Enter any passphrase:”, you should enter any one of the existing password for the /dev/sdb1. As we saw above, this already had two password from Slot 0 and Slot 1. You should enter any one of those password first.
• Once you enter an existing password, then you can assign a new LUKS key.

Anytime you add a new LUKS key, it will be added to the next available slot. Since we already had two existing Keys, the new key was added to the slot#2, which was the next available slot.

So, Slot#0 through 2 will says “ENABLED”. We have three LUKS keys on /dev/sdba1.

# cryptsetup luksDump /dev/sdb1 | grep Slot
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

3. Add New LUKS Key to a Specific Slot

Instead of LUKS adding the new key to the next available slot, you can also add new key to a specific slot.

For this use -S option in the cryptsetup luksAddKey as shown below.

In this example, we are adding new LUKS key to Slot#5. I assigned the new passphrase as: PasswordforSlot5

# cryptsetup luksAddKey /dev/sdb1 -S 5

As we see below, now Slot#5 says “ENABLED”, while slot#3 and #4 are still in DISABLED state.

# cryptsetup luksDump /dev/sdb1 | grep Slot
Key Slot 0: ENABLED
Key Slot 1: ENABLED
Key Slot 2: ENABLED
Key Slot 3: DISABLED
Key Slot 4: DISABLED
Key Slot 5: ENABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

At this stage, we have 4 LUKS key assigned to /dev/sdb1 encrypted partition.

4. Delete an Existing LUKS Key

To remove an existing key from LUKS partition, use cryptsetup luksRemoveKey as shown below.

In this example, you just have to enter the password (key) that you want to be erased.

Remove/Erase/Delete a LUKS key from a slot. You don’t have to specify the slot number. Instead specify the key to be deleted!.

In this example, when it prompts “Enter LUKS passphrase to be deleted:”, I entered the key that created in the previous example: PasswordforSlot5

# cryptsetup luksRemoveKey /dev/sdb1
Enter LUKS passphrase to be deleted: 

As you see from the following luksDump output, the key in Slot#5 is now erased.

# cryptsetup luksDump /dev/sdb1 | grep Slot
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

5. Delete a LUKS Key using luksKillSlot

If you don’t have the key for a particular slot, but want to just delete it, you can do it using cryptsetup luksKillSlot command as shown below.

In this example, we are deleting the key from LUKS slot#2.

For this, you have to enter the LUKS key for any one of the slots. This is only as a validation before it delete the Key from slot#2.

# cryptsetup luksKillSlot /dev/sdb1 2
Enter any remaining LUKS passphrase: 

As you see from the following luksDump output, the key in Slot#2 is now erased.

# cryptsetup luksDump /dev/sdb1 | grep Slot
Key Slot 0: ENABLED
Key Slot 1: ENABLED
Key Slot 2: DISABLED
Key Slot 3: DISABLED
Key Slot 4: DISABLED
Key Slot 5: DISABLED
Key Slot 6: DISABLED
Key Slot 7: DISABLED

6. Add New LUKS Key from a File

You can also add a new LUKS key based on a keyfile that you already have as shown below.

# cryptsetup luksAddKey  /dev/sdb1 masterkeyfile
Enter any passphrase: 

In the above:

• masterkeyfile contains the new LUKS key that you want to add. This should be a binary file.
• When it prompts “Enter any passphrase:”, enter any one of the existing LUKS keyu for /dev/sdb1 partition.
• As you see above, it didn’t prompt for new LUKS key, as it took it from the masterkeyfile.

As you see from the following luksDump output, this new key from the masterkeyfile is added to slot#2

# cryptsetup luksDump /dev/sdb1 | grep Slot
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

7. Reset Forgotten LUKS Key – Get Existing Key

If you rebooted the server, and unable to mount your encrypted LUKS partition, because you’ve forgotten your LUKS password, then you are out of luck, you can reset it.

But, if an encrypted LUKS partition is already opened, and if you have not rebooted the system, and you’ve forgot the LUKS password for the partition that is already mounted (at least LUKS opened once since the last reboot), then you can assign a new LUKS key.

In this “forgot my LUKS password” scenario, you can do the following two steps:

1. Extract the current encrypted key from the LUKS partition
2. Create a new LUKS key using the above extracted encrypted key

In this example, I have the /home1 partition mounted, which is a LUKS encrypted partition, but I don’t have the password for this.

# df -h
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda1             127G   44G   76G  37% /
/dev/mapper/home1      93G  188M   88G   1% /home1

The volume name is whatever is there after “/dev/mapper/” in the 1st column of the above df command output. So, in our example, the volume name is “home1”

The following dmsetup table –showkeys will show the encrypted keys of all the partitions that are mounted on your system.

# dmsetup table --showkeys 
home1: 0 197259264 crypt aes-cbc-essiv:sha256 607f482870c795a9b1e307ffbfc6643eaa219e9ef8c6773de02cd298c8fcda3c 0 8:17 4096

The field after “aes-cbc-essiv:sha256” is the encrypted password. Get the encrypted LUKS key and store it in a file.

# vi existinglukskey.txt
607f482870c795a9b1e307ffbfc6643eaa219e9ef8c6773de02cd298c8fcda3c

8. Reset Forgotten LUKS Key – Create Binary Key file

Now, we have to convert this existing key from a text file to a binary file. Use xxd command as shown below.

# xxd -r -p existinglukskey.txt existinglukskey.bin

In the above:

• -r option is for reverse. This will convert the hexdump into binary.
• -p option is for postscript. This indicates postscript continuous hexdump style.
• existinglukskey.txt input file
• existinglukskey.bin output file. This will now contain the existing encrypted LUKS password in a binary file.

9. Reset Forgotten LUKS Key – Add a New Key

Finally, add a new LUKS key by using the existing LUKS key that we extracted into the binary file.

# cryptsetup luksAddKey /dev/sdb1 --master-key-file <(cat existinglukskey.bin)
Enter new passphrase for key slot: 
Verify passphrase: 

In the above:

• –master-key-file Specify the binary file here. Don’t use the existinglukskey.txt. Instead use the existinglukskey.bin that we created above.
• As you see above, the luksAddKey didn’t ask for existing LUKS password, as it took it from the binary file.
• When it prompts “Enter new passphrase for key slot:”, enter the new LUKS password. But, this time, don’t forget this.

Again, remember this: If you forget the LUKS password after you reboot the system, you are out of Luks (out of luck), as you can’t reset it.

10. Dump LUKS MasterKey

You can also dump the MasterKey and keep it safe somewhere. Use the –dump-master-key option along with luksDump as shown below.

# cryptsetup luksDump --dump-master-key /dev/sdb1
Are you sure? (Type uppercase yes): YES
Enter LUKS passphrase: 
LUKS header information for /dev/sdb1
Cipher name:    aes
Cipher mode:    cbc-essiv:sha256
Payload offset: 4096
UUID:           146d639a-757c-4bcb-aee6-8fe815345104
MK bits:        256
MK dump:        60 7f 48 28 70 c7 95 a9 b1 e3 07 ff bf c6 64 3e 
                aa 21 9e 9e f8 c6 77 3d e0 2c d2 98 c8 fc da 3c 

Keep in mind that you have to store the LUKS header dump in a safe place. Using the master key dump, someone can get to the LUKS encrypted partition.