User:Sakaki/Sakaki's EFI Install Guide/Migrating from Whirlpool Hash on LUKS

Previous versions of this install guide recommended the Whirlpool hash algorithm for use, when creating the LUKS partition on your system's hard drive.

Unfortunately, there is a bug in the implementation of Whirlpool in the library (versions < 1.6), which   uses. As a result (per this Arch Linux bug report), if you update  to version >= 1.6 (for example, by running   after 1.6.2 has been stabilized), you will no longer be able to open the LUKS partition (since the correct implementation in the new version will not match the incorrect one used in the LUKS header).

The install guide has been modified to reflect this bug, and now recommends the use of SHA-512 hashing instead (which is correctly implemented in both version 1.5 and 1.6 of ).

However, existing users will need to migrate their LUKS header to use a different hash. The below guide provides short form instructions for doing this (when using a GPG-encrypted keyfile, per the guide). It is patterned on the advice in this email from the  archives.

This migration process should leave all your LUKS data and software intact. Also, although best done pre-emptively, even if you have already upgraded to >= 1.6, and thereby locked yourself out, you should still be able to use the instructions below to recover. However, proceed at your own risk!

Prerequisites
To carry this out, you will need:
 * 1) your boot USB key (on which the file   has been stored);
 * 2) the target PC, on which the LUKS partition (created using the buggy  (< 1.6) implementation of Whirlpool) resides; and
 * 3) a second USB key (of at least 300MB capacity), which we'll use to hold a Gentoo minimal-install disk image (this will let us access your LUKS partition in its closed state); I'll refer to this as the ISO USB key in the below.

We'll be using tools downloaded from this GitHub repository to facilitate the migration. There are digital signatures there you can check if you wish to do so; I will omit that process in what follows, for brevity.

Migration
On an appropriate PC (as root), insert your ISO USB key, unmount any partitions of it that may have automounted (using ), and then issue the following to download and write the appropriate Gentoo minimal install ISO:

Remove the ISO USB key, and insert it into your (powered down) target PC. Make sure your boot USB key is not inserted at this point. Power up the target, enter the BIOS, set legacy / CSM boot (and ensure secure boot is off), and choose to boot from USB (essentially, exactly as per these instructions). Press at the ISOLINUX boot prompt as usual, and set an appropriate keymap when asked. You should now be looking at the familiar livecd prompt.

Now bring networking up (as per these instructions). Once you have done this, download the (prebuilt)  utility:

You're now ready to go. Insert your boot USB key (which has the  encrypted keyfile on it), and determine its device path (you can use   to help you do this). In what follows, I'm going to use: Substitute appropriate values for your system in the following commands.
 * to refer to the first partition of the boot USB key (where  resides, it will probably be something like ), and
 * to refer to your LUKS partition (e.g. ).

Begin by setting up  so that we can decrypt the keyfile. Issue:

Your output will differ from the above, but whatever is shown, copy and paste it at the command prompt, and press :

Mount the boot USB key, so we can use the keyfile:

Now check that you can indeed open your existing LUKS partition:

Look at the device mapper, to verify that our  LUKS device is now present:

If you see something similar to the above, you should be good to go. Close the LUKS partition again:

One last preliminary: let's make a header backup of your LUKS partition, so we can get it back if something should go wrong:

Right, let's do the migration!

When that returns, check that the hash is now reported as ; issue:

If good, check that you can still open the LUKS partition:

Assuming that worked, congratulations, you have migrated your LUKS hash successfully! Close the LUKS partition again, and unmount your boot USB key:

That's it! Reboot:

Enter the BIOS, and reset (if you have got to the appropriate stage in the tutorial) EFI and secure boot. Remove the ISO USB key, it can be reformatted now if you like. Select (in the BIOS) the EFI boot key as the boot device, and restart.

You should now be able to unlock the disk as usual (entering your GPG passphrase), and then log in.

Final Steps
If you added  (or similar) to, you can safely remove that now - your LUKS system will work even with updated (>=1.6) versions of.