Note that while the private endpoints are used in this example, public endpoints for IAM, Key Protect, and HPCS can also be used.
- Create an IBM Cloud IAM API key to access your resource.
- A skeleton /etc/hpcs-for-luks.ini file is included in the hpcs-for-luks package. Edit it with the information obtained above.
- Put "placeholder" for default_crk_uuid for now (it will be set later):
[KP]
api_key = AB0CdEfGHijKlMN--12OPqRStuv3wx456yZAb7CDEF8g
region = us-east
service_instance_id = 01234567-89ab-cdef-0123-456789abcdef
endpoint_url = https://api.private.us-east.hs-crypto.cloud.ibm.com:9730
default_crk_uuid = fedcba98-7654-3210-fedc-ba9876543210
Test the configuration by attempting to list keys in the KMS:
hpcs-for-luks list
If the test fails, check for typos, check on the status of your instance via the portal, diagnose the problem, and retry.
Generate a customer root key (CRK)
Now that the hpcs-for-luks
utility is configured, you can use it to generate a CRK:
Generate a CRK in the KMS:
hpcs-for-luks create --crk --gen --name MyCRKName
List the keys to get the ID associated with MyCRKName:
hpcs-for-luks list | grep MyCRKName
Because the CRK is frequently used and seldom changed, it is convenient to configure the hpcs-for-luks utility to use it. Edit /etc/hpcs-for-luks.ini and change the "placeholder" value for default_crk_uuid to the ID you just obtained above:
[KP]
api_key = AB0CdEfGHijKlMN--12OPqRStuv3wx456yZAb7CDEF8g
region = us-east
service_instance_id = 01234567-89ab-cdef-0123-456789abcdef
endpoint_url = https://api.private.us-east.hs-crypto.cloud.ibm.com:9730
default_crk_uuid = fedcba98-7654-3210-fedc-ba9876543210
Wrap the LUKS passphrase
Now that hpcs-for-luks is configured with a root key wrap the passphrase used for the new encrypted root partition. The following command wraps the “MyPhrase” passphrase and stores the wrapped passphrase into the “luks:root” file. The hpcs-for-luks module will use this wrapped phrase to open the encrypted root partition during boot.
echo -n 'MyPhrase' | hpcs-for-luks wrap > /var/lib/hpcs-for-luks/user/luks:root
Add a token to the cryptsetup of the encrypted partition. This updates the configuration of the encrypted partition to use a Linux kernel key for opening the partition.
cryptsetup token add /dev/sda6 --key-description luks:root
Enable the hpcs-for-luks-wipe service which removes the keys hpcs-for-luks adds to the kernel key ring when the boot process is finished with them.
systemctl enable hpcs-for-luks-wipe
Test hpcs-for-luks processing
Test the hpcs-for-luks processing of the wrapped passphrase and the automatic opening of the partition.
First, close the encrypted partition:
cryptsetup close root
Next, have hpcs-for-luks process the wrapped key and add it to the Linux kernel keyring:
hpcs-for-luks process
Open the encrypted partition. This command should run and open the partition without asking for a passphrase. If it prompts for a passphrase there is a configuration problem from one of the previous steps which needs to be fixed before proceeding.
cryptsetup open /dev/sda6 root
Configure dracut modules and rebuild the initramfs
Now that hpcs-for-luks is configured to open the encrypted root partition with the wrapped passphrase, configure the required dracut modules for hpcs-for-luks and rebuild the initramfs to include the hpcs-for-luks module.
This builds the wrapped passphrase file into the initramfs and configures hpcs-for-luks in the initial boot steps so it can unwrap and add the LUKS passphrase to a kernel key so LUKS can automatically open the encrypted root partition.
Add the required modules to the /etc/dracut.conf.d/hpcs-for-luks.conf file so that the contents of the file look like this:
add_dracutmodules+=" hpcs-for-luks crypt ifcfg network network-manager url-lib"
The initramfs can now be rebuilt to include the wrapped passphrase and the hpcs-for-luks module.
Dracut version 057 which is included in Red Hat Enterprise Linux 9.2 has a bug which assumes that dracut is being run with a umask value of 022. This is not the default umask of the root user in the stock image. Therefore, the umask must be changed to 022 before running dracut and set back afterward. The following commands change umask around the dracut command to correctly rebuild the initramfs:
INITIAL_UMASK=`umask`
umask 022
dracut --force --verbose
umask $INITIAL_UMASK
Increase the GRUB menu timeout value
When the bare metal server boots a menu is shown on the console which allows the user to select different boot configurations. Later in this tutorial a new boot menu option will be added for the encrypted root partition and the encrypted root partition option will be set as the default.
The default timeout value to choose a boot configuration is 2 seconds. If you want to change this value to give more time to select the non-encrypted operating system partition it is best to do it now before the operating system is copied into the encrypted partition.
1. Edit /etc/default/grub
2. Change the GRUB_TIMEOUT value to your desired time in seconds.
3. Run the following two commands:
grub2-mkconfig -o /boot/efi/EFI/redhat/grub.cfg
grub2-mkconfig -o /boot/grub2/grub.cfg
Copy the unencrypted root partition operating system to the encrypted file system
Now that the hpcs-for-luks configuration is complete the next step is to copy the operating system into the encrypted partition and file system.
First mount the encrypted root file system:
mkdir /mnt/encryptedroot
mount /dev/mapper/root /mnt/encryptedroot
Next copy the operating system into the encrypted root:
rsync -a --exclude='/proc/*' --exclude='/sys/*' --exclude='/boot' --exclude='/mnt/encryptedroot' / /mnt/encryptedroot
After the operating system is copied, the update fstab and crypttab files for the encrypted root partition.
The crypttab file need values from the lsblk output:
lsblk -f
NAME FSTYPE FSVER LABEL UUID FSAVAIL FSUSE% MOUNTPOINTS
sda
├─sda1
├─sda2 vfat FAT16 7B77-95E7 192.8M 3% /boot/efi
├─sda3 xfs boot e78d6a6f-15cc-469b-83ab-9a60b7b574f0 226.1M 54% /boot
├─sda4 xfs root d370e124-ea83-46ea-a7ef-67f12dd8bb3c 7.7G 17% /
├─sda5 iso9660 Joliet Extension cidata 2023-11-30-13-54-10-00
└─sda6 crypto_LUKS 2 8a374993-d8f4-42ff-92ce-25da7977b7c0 └─root
Edit or create the /mnt/encryptedroot/etc/crypttab file and add this line:
root UUID=8a374993-d8f4-42ff-92ce-25da7977b7c0 none luks,_netdev
The UUID value should come from the crypto_LUKS 2 partition that was added for the encrypted root.
Edit the /mnt/encryptedroot/etc/fstab file. Remove the line that has the single “/” for the root file system and add following line in its place:
/dev/mapper/root / xfs defaults 0 1
Add the encrypted root boot as GRUB option
To boot from the encrypted root partition, it needs to be added as an option in GRUB. To add this option, first look at the existing entries using grubby command:
grubby --info ALL
Using the same kernel and initrd name as the index=0 value from the above command, add the encrypted root partition option with the following command. Note the rd.luks.name value is the UUID of the sda6 crypto_LUKS2 partition from the lsblk -f output above.
grubby --add-kernel="/boot/vmlinuz-5.14.0-284.25.1.el9_2.x86_64" \
--title="Boot from encrypted root" \
--initrd="/boot/initramfs-5.14.0-284.25.1.el9_2.x86_64.img" \
--args="ro console=tty0 console=ttyS0,115200n8 no_timer_check net.ifnames=0 rd.shell rd.hpcs-for-luks log_buf_len=1M rd.neednet=1 root=/dev/mapper/root rd.luks.name=8a374993-d8f4-42ff-92ce-25da7977b7c0=root ip=dhcp"
Verify the kernel/menu option was added and get its index number.
grubby --info ALL
index=0
kernel="/boot/vmlinuz-5.14.0-284.25.1.el9_2.x86_64"
args="ro no_timer_check net.ifnames=0 console=ttyS1,115200n8 console=tty0 efi=noruntime"
root="UUID=d370e124-ea83-46ea-a7ef-67f12dd8bb3c"
initrd="/boot/initramfs-5.14.0-284.25.1.el9_2.x86_64.img"
title="Red Hat Enterprise Linux (5.14.0-284.25.1.el9_2.x86_64) 9.2 (Plow)"
id="5ab34399c941d21ae071deafd950883c-5.14.0-284.25.1.el9_2.x86_64"
index=1
kernel="/boot/vmlinuz-5.14.0-284.25.1.el9_2.x86_64"
args="ro console=tty0 console=ttyS0,115200n8 no_timer_check net.ifnames=0 rd.shell rd.hpcs-for-luks log_buf_len=1M rd.neednet=1 ip=dhcp rd.luks.name=8a374993-d8f4-42ff-92ce-25da7977b7c0=root"
root="/dev/mapper/root"
initrd="/boot/initramfs-5.14.0-284.25.1.el9_2.x86_64.img"
title="Boot from encrypted root"
In the above output the new boot option has been added with index=1. To make the bare metal server boot from the encrypted partition by default, set the default index to 1 using the following command:
grubby --set-default 1
With IBM Cloud Bare Metal Servers on VPC and Red Hat Enterprise Linux 9.2, the grubenv file must be copied for the default index change to take effect:
cp /boot/grub2/grubenv /boot/efi/EFI/redhat/
The system is now ready to reboot and boot from the encrypted root partition.
Rebooted server view
Upon reboot the system console will show the new GRUB menu entry as shown in this screen shot: