Drive encryption is one of Unraid's many good features. When you encrypt part or all of your array and cache, at some point you might end up wanting to change your unlock key. Just how often, would depend on your threat model (and on your level of paranoia).

At this time (6.8), Unraid does not have a UI for changing the unlock key.

 

Here is a small tool that will let you change your unlock key.

Each of the current and new unlock keys can either be a text password / passphrase, or a binary key file if you're into those (I am). 

 

Your array must be started to use this tool.

 

Essentially, the script validates the provided current key against your drives, and on all drives that can be unlocked with the current key, replaces it with the new one (in fact, it adds the new key to all of them, and upon success, removes the old key from all of them).

Important: The tool does not save the provided new (replacement) key on permanent storage. Make very sure you have it backed up, either in memory (...) or on some permanent storage (not on the encrypted array 😜 ). If you misplace the new key, your data is hosed.

 

Currently this script needs to be run from the command line. I may turn it into a plugin if there's enough interest (and time) - although I'm pretty sure Limetech has this feature on their radar for some upcoming version.

 

Usage:  unraid-newenckey [current-key-file] [new-key-file]

Both positional arguments are optional and may be omitted.

If provided, each of them is either the name of a file (containing a passphrase or a binary key), or a single dash (-). 

 

For each of the arguments, if it is either omitted or specified as a dash, the respective key will be prompted for interactively.

Note: if you provide a key file with a passphrase you later intend to use interactively when starting the array (the typical use case on Unraid), make sure the file does not contain an ending newline. One good way to do that is to use "echo -n", e.g.:

      echo -n "My Good PassPhrase" > /tmp/mykeyfile

This code has been tested, but no warranty is expressed or implied. Use at your own risk.

With the above out of the way, please report any issues.

 

EDIT 2022-06-07: The recommended way to install this is to use the plugin - look for "New Unlock Key for Encrypted Drives" on Community Apps. I'm leaving the script attached here for now, but updates will be provided via the plugin (currently at version 0.9).

 

EDIT 2021-08-16: Posted an updated version for Unraid 6.10. The 6.10 OS includes an updated "lsblk" command which is not backwards compatible.

 

 

 

Edited May 24, 20242 yr by doron
Remove attached script; installation via plugin

Very nice.  Similar to what we want to do, except I was also going to back up the LUKS headers first because I'm just that paranoid 😋

Just  want to say that I used this script and it worked as expected. Thanks!

41 minutes ago, Niklas said:

Just  want to say that I used this script and it worked as expected. Thanks!

Thanks for reporting! This is good to hear.

@doron, thank you. The script work verywell, fast and as expected! Save my time, be healthy.

3 hours ago, b0n3v said:

@doron, thank you. The script work verywell, fast and as expected! Save my time, be healthy.

Thanks for reporting, @b0n3v. Glad it worked for you. Stay safe and healthy.

Is there any way to use the script to switch from a password encrypted array (manual entry on array start, no keyfile) to an encrypted array with a keyfile?

8 minutes ago, DaveDoesStuff said:

Is there any way to use the script to switch from a password encrypted array (manual entry on array start, no keyfile) to an encrypted array with a keyfile?

Sure. Once you have your keyfile generated (and backed up in a few places 🙂 ), place it somewhere accessible and then:

unraid-newenckey - <keyfilepath>

The dash indicates "prompt for key from console", which is what it will do.

Just now, doron said:

Sure. Once you have your keyfile generated (and backed up in a few places 🙂 ), place it somewhere accessible and then:

unraid-newenckey - <keyfilepath>

The dash indicates "prompt for key from console", which is what it will do.

Thanks for that, I've been pouring over the forums/wiki trying to figure out how to switch to a keyfile from a passphrase or what the format of the keyfile should be/how to generate one. It's a surprisingly poorly documented feature (would love to be proven wrong on that).

I'll give it a try when I'm back at my desk tonight. Thanks again!

A keyfile could in fact be anything - just any file. Some people generate 32 random bytes from /dev/random, some use existing files.

Just make sure you hold on to it 🙂 

On 10/9/2020 at 2:21 PM, doron said:

A keyfile could in fact be anything - just any file. Some people generate 32 random bytes from /dev/random, some use existing files.

Just make sure you hold on to it 🙂 

So I ran the script as described. It listed all my drives and asked me to confirm I wanted to use my new keyfile. I confirmed and did the restart once completed. Now the array won't start with missing key error.

 

Even if I select the keyfile manually through the GUI it still fails. Passkey also fails.

 

The keyfile itself is located in /boot/config/keyfile

 

It is a single line keyfile with a simple string of random characters.

 

Any advice would be appreciated!

 

EDIT: Something strange I have noticed is that on the main page in GUI mode 2 of the disks in my array have green lock icons (encrypted) while the other 5 disks plus my cache all have a yellow lock icon (to be encrypted). 

 

EDIT2: It turned out to be a spelling mistake in my "go" file that meant the system link from root to the keyfile. This fixed the missing key issue. However 5 array devices and my cache (4 drives) are all showing yellow lock icons (to be encrypted) and main is giving me the option to format.

 

Also my unassigned device that runs all my vms and docks is now showing up as new

Edited October 13, 20205 yr by DaveDoesStuff
Update

@DaveDoesStuff - Just so I understand the current situation - so you have the key in /root/keyfile and some of your drives won't open when you start the array?

 

If you just copy the key file to /root/keyfile and then start the array - what do you get?

23 minutes ago, doron said:

@DaveDoesStuff - Just so I understand the current situation - so you have the key in /root/keyfile and some of your drives won't open when you start the array?

 

If you just copy the key file to /root/keyfile and then start the array - what do you get?

So it turned out that issue was caused by a bad system link for "keyfile" already being in root (fry config file).

 

The other issue (I discovered too late as I already mistakenly formatted some drives) was caused by an inadvertent downgrade to an older version of unraid via the unraidDVB plugin

 

My last remaining issues are that my unassigned device (an SSD) that hosts all my VMs is now unable to be mounted with the error: "unassigned.devices: luksOpen error: No key available with this passphrase."

 

...that has to be related right? The weird thing is the file system on the UD is just "luks"...

 

Also on a less urgent note the array won't autostart, it tells me autostart is disabled on boot. But the UD problem is far more important as my pfsense VM is on there and without it I have a house with no internet and a very angry wife!

 

Edited October 13, 20205 yr by DaveDoesStuff
Spelling

51 minutes ago, doron said:

@DaveDoesStuff - Just so I understand the current situation - so you have the key in /root/keyfile and some of your drives won't open when you start the array?

 

If you just copy the key file to /root/keyfile and then start the array - what do you get?

 

35 minutes ago, DaveDoesStuff said:

So it turned out that issue was caused by a bad system link for "keyfile" already being in root (fry config file).

 

The other issue (I discovered too late as I already mistakenly formatted some drives) was caused by an inadvertent downgrade to an older version of unraid via the unraidDVB plugin

 

My last remaining issues are that my unassigned device (an SSD) that hosts all my VMs is now unable to be mounted with the error: "unassigned.devices: luksOpen error: No key available with this passphrase."

 

...that has to be related right? The weird thing is the file system on the UD is just "luks"...

 

Also on a less urgent note the array won't autostart, it tells me autostart is disabled on boot. But the UD problem is far more important as my pfsense VM is on there and without it I have a house with no internet and a very angry wife!

 

This is definitely down to the key change, if I remove the line in my go file where I point it at the keyfile and instead out in a passphrase them all the drives that accepted the keyfile become locked and my unassigned device suddenly becomes mountable.

 

Is there a workaround for this or if not a way to switch back to my old passphrase?

7 minutes ago, DaveDoesStuff said:

So it turned out that issue was caused by a bad system link for "keyfile" already being in root (fry config file).

That's good news. My advice: do not link. Copy.

On your go file, just cp /boot/config/keyfile /root/

7 minutes ago, DaveDoesStuff said:

 

The other issue (I discovered too late as I already mistakenly formatted some drives) was caused by an inadvertent downgrade to an older version of unraid via the unraidDVB plugin

Ouch. Sounds painful.

 

7 minutes ago, DaveDoesStuff said:

 

My last remaining issues are that my unassigned device (an SSD) that hosts ally VMs is now unable to be mounted with the error: "unassigned.devices: luksOpen error: No key available with this passphrase."

 

...that has to be related right? The weird thing is the file system on the UD is just "luks"...

Hmm. 

So let's zoom in on that drive and take it step by step.

1. Are you sure that drive was on the list of drives you changed the key for? Could it be that it was not, and now it's expecting the old key?

2. Did the script complete successfully? Did you record (or can you still find) its console output?

 

Assuming this UD drive is sdX, please try --

cryptsetup luksOpen --test-passphrase --key-file /root/keyfile /dev/sdX1

(Note the 1 at the end of the drive name - first partition)

If this fails, try without the keyfile:

cryptsetup luksOpen --test-passphrase /dev/sdX1

When prompted, provide your old key. If this one works, we've found the problem. If this is the case, post here and I'll guide you through changing the key manually (basically you need to add the new key, and only once successful, remove the old key - or, you can even leave the old key be, LUKS works perfectly well with two keys).

 

7 minutes ago, DaveDoesStuff said:

 

Also on a less urgent note the array won't autostart, it tells me autostart is disabled on boot. But the UD problem is far more important as my pfsense VM is on there and without it I have a house with no internet and a very angry wife!

 

Not sure about the autostart but avoiding an angry wife is our first priority.

5 minutes ago, doron said:

That's good news. My advice: do not link. Copy.

On your go file, just cp /boot/config/keyfile /root/

Ouch. Sounds painful.

 

Hmm. 

So let's zoom in on that drive and take it step by step.

1. Are you sure that drive was on the list of drives you changed the key for? Could it be that it was not, and now it's expecting the old key?

2. Did the script complete successfully? Did you record (or can you still find) its console output?

 

Assuming this UD drive is sdX, please try --

cryptsetup luksOpen --test-passphrase --key-file /root/keyfile /dev/sdX1

(Note the 1 at the end of the drive name - first partition)

If this fails, try without the keyfile:

cryptsetup luksOpen --test-passphrase /dev/sdX1

When prompted, provide your old key. If this one works, we've found the problem. If this is the case, post here and I'll guide you through changing the key manually (basically you need to add the new key, and only once successful, remove the old key - or, you can even leave the old key be, LUKS works perfectly well with two keys).

 

Not sure about the autostart but avoiding an angry wife is our first priority.

Firstly thank you for the help, it's 1am here now and I'm at my wit's end lol.

 

I just posted prior to your reply that I got the UD to accept the old key. So if you could talk me through adding the new keyfile (/boot/config/keyfile) to that drive I would appreciate it.

 

The identifier of the UD in question is sdo according to the GUI.

Edited October 14, 20205 yr by DaveDoesStuff

3 minutes ago, DaveDoesStuff said:

 

This is definitely down to the key change, if I remove the line in my go file where I point it at the keyfile and instead out in a passphrase them all the drives that accepted the keyfile become locked and my unassigned device suddenly becomes mountable.

 

Is there a workaround for this or if not a way to switch back to my old passphrase?

Ah. Our posts crossed paths. So this is exactly what I suspected. The script did not deal with the UD device (will need to figure out why - perhaps it wasn't mounted at the time the script ran?) so the UD device is still with the old key.

 

This is easily solvable. You want to add the new key to the UD device. Let's do it manually. Assume the UD drive is sdX . Then, you want to:

cryptsetup luksAddKey /dev/sdX1 /root/keyfile

This should prompt you for the current ("old") key. Just type it in. Once this completes successfully, everything should work with the new key.

 

If you want you can later remove the old key, but as I said there's no harm in having two.

 

Lemme know how you fare.

Yes, the script would in most cases skip handling the UD enrcypted drives. This is due to the naming convention used by UD. I'll look into changing the code so it handles these too.

24 minutes ago, doron said:

Ah. Our posts crossed paths. So this is exactly what I suspected. The script did not deal with the UD device (will need to figure out why - perhaps it wasn't mounted at the time the script ran?) so the UD device is still with the old key.

 

This is easily solvable. You want to add the new key to the UD device. Let's do it manually. Assume the UD drive is sdX . Then, you want to:

cryptsetup luksAddKey /dev/sdX1 /root/keyfile

This should prompt you for the current ("old") key. Just type it in. Once this completes successfully, everything should work with the new key.

 

If you want you can later remove the old key, but as I said there's no harm in having two.

 

Lemme know how you fare.

Works like a charm! You are an absolute hero man. I was so frantic over the slight data loss/other issues earlier (which were totally unrelated to your script) that I would have struggled to figure out how to do that.

I really wish I had spotted that damn rollback from the unraidDVB plugin earlier before my (accidentally/stupid) formatting etc, I'd be 100% if it wasn't for that. Definitely need to learn not to panic lol!

 

7 minutes ago, doron said:

Yes, the script would in most cases skip handling the UD enrcypted drives. This is due to the naming convention used by UD. I'll look into changing the code so it handles these too.

 

To be fair I had actually completely forgotten I had added encryption to that UD. But in hindsight I must have done it when I moved over some dockers/vms there due to performance issues when they were running from cache. This is something I should have remembered/noticed (during the key replacement) as missing from the scripts output/confirmation. So again not you or the scripts fault. All on me.

 

I plan on getting 2x 1TB NVMEs in the future to replace both my cache (4x 250GB) and the UD SSD...I really wish I had done it already after this haha!

 

Luckily I at least had regular config file backups so that was easy to fix, but this (and some other incidents) has really opened my eyes to the fact that I should have a seconday offsite storage/backup setup. So that is going to come before the new NVMEs I think.

 

In summary: THANK YOU!!!

You're very welcome, glad it helped.

I've just posted a new version on the top post (0.6). It should cover all mounted encrypted (LUKS) drives, be it array, cache or UD managed.

 

Enjoy, and stay healthy and safe.

Edited October 16, 20205 yr by doron

Curious what you make of this @doron, I've been having an issue whereby my UD NVME drive won't auto mount on system startup after a reboot. I posted over in the UD thread and supplied my diagnostics and dlandon suggested the issue below is my problem. Seems a bit coincidental right?

 

 

What do you think? Possible sidefffect of the sript or unrelated and a 6.8.3 issue? (dlandon didn't know I'd run a script to replace my keys)

14 minutes ago, DaveDoesStuff said:

Curious what you make of this @doron, I've been having an issue whereby my UD NVME drive won't auto mount on system startup after a reboot. I posted over in the UD thread and supplied my diagnostics and dlandon suggested the issue below is my problem. Seems a bit coincidental right?

 

 

What do you think? Possible sidefffect of the sript or unrelated and a 6.8.3 issue? (dlandon didn't know I'd run a script to replace my keys)

My initial guess is it's a small issue in Unassigned Devices. The error from luksOpen is just a warning, but UD interprets the nonzero rc as an error and gives up.

 

What happens if you mount it from the UI? Does it work fine and mount the drive?

 

 

3 minutes ago, doron said:

My initial guess is it's a small issue in Unassigned Devices. The error from luksOpen is just a warning, but UD interprets the nonzero rc as an error and gives up.

 

What happens if you mount it from the UI? Does it work fine and mount the drive?

 

 

Yep, absolutely fine.

5 hours ago, DaveDoesStuff said:

Yep, absolutely fine.

I looked at the UD code and indeed this is the case. When it issues the luksOpen command it expects a null (empty) response on stdout. When there's any (warning) message there, it assumes luksOpen failed and barfs.

 

I suppose you can work around that by creating the directory /run/cryptsetup in your go script (permissions must be 700), which will eliminate the warning message and therefore the failure, but best would be for UD to fix that.

 

EDIT: If you do want the workaround, just add this to your go script:

mkdir -pm 700 /run/cryptsetup

 

Edited October 19, 20205 yr by doron