The primary goal of this project is to prevent unauthorized boot chains (from BIOS up to launching init) from accessing the data on an encrypted root device while allowing authorized boot chains to mount that device at boot time without user interaction (such as passphrase entry). Specific functional requirements include:
Presently, a bunch of scripts and a Makefile that, when used on a machine with a LUKS-encrypted root filesystem and a UEFI firmware, will result in a TPM 2.0-enabled measured Linux boot supporting non-interactive mount of the encrypted root volume.
The installation procedure requires that your system be prepared in a few specific ways:
/boot
must not be a separate partition, but instead must be hosted on the encrypted root device. (This is mainly a safety measure to prevent any unintended future use of unprotected boot chains.)/boot/efi
with sufficient space to allow the installation of two kernel blobs (each roughly the size of the kernel and initrd combined: for future growth in kernel sizes, target 500M or more).The easiest way to meet most of these requirements is to get grub-efi 2.06 working with GRUB encrypted boot (GRUB_ENABLE_CRYPTODISK=y
in /etc/defaults/grub
) and verify that you can boot using the GRUB UEFI entry by entering the root passphrase when GRUB first starts up. While the result of installing this measured boot solution bypasses GRUB, I recommend retaining a working grub-efi install for recovery and for debugging when the ability to change the kernel command line is required.
Note: the build of GRUB 2.06 currently in Debian's unstable repository does not have LUKS2 support built in, which means you'll need to build your own with that support; and it appears to break GRUB_ENABLE_CRYPTODISK=y
, for which the easiest resolution is to create a boot entry pointing at the monolithic EFI image copied manually to the EFI system partition. For the latter, I recommend copying it to a different location (e.g., /boot/efi/EFI/debian/grubx64ml.efi
) and creating an EFI entry pointing at it (e.g., efibootmgr -c -L 'GRUB (monolithic)' -l '\EFI\debian\grubx64ml.efi'
), so subsequent runs of grub-install
do not override your changes.
Roughly speaking, the steps involved in preparation for install are:
EF00
) so it is at least 500M. (I personally have 1G ESPs. I'm not gonna miss the space, but I will very much feel the annoyance at having to increase its size again during the lifetime of a machine.)
resize2fs
, then lvresize
(if necessary), then pvresize
, then cryptsetup resize
, then mdadm --grow
(yes, --grow
is also used to shrink), then gdisk
or parted
; then partprobe
; and then do it all in the reverse order without any sizes specified (layer sizes will be auto-detected) to make sure there's no abandoned space./etc/fstab
mounting it at /boot/efi
.mkdir -p /boot/efi && mount /boot/efi
EF02
) to support booting grub-pc from a GPT-partitioned disk. This can be tiny (e.g., 1MB), but IIRC it needs to be near the start of large disks because of BIOS geometry limitations (even with LBA translation). Beyond that, you don't need to format or mount this anywhere: GRUB will handle it.grub-install /dev/sda
for boot disk /dev/sda
) with the updated partition scheme and reboot to make sure the system is bootable before continuing.GRUB_ENABLE_CRYPTODISK=y
to /etc/default/grub
. (Note: This is currently broken in Debian GRUB 2.06, as even with this option the monolithic grub-efi loader is not installed into the ESP.)/boot
. One way to do this is:
/boot/efi
temporarily./boot
and remount it somewhere else (e.g., /mnt
)./boot
(e.g., tar -C /mnt -c . | tar -C /boot -xvp
)./boot/efi
./boot
entry in /etc/fstab
.grub-install /dev/sda
for boot disk /dev/sda
) with the updated partition scheme, and then reboot to make sure the system is bootable before continuing. If your root device is currently encrypted, you will be prompted for the LUKS passphrase when GRUB starts.cryptsetup reencrypt
to encrypt your disk. This only supports LUKS2 metadata, so you can skip the LUKS1-to-LUKS2 conversion. Note: GRUB 2.06 does not support argon2 PBKDF, so make sure to specify --pbkdf pbkdf2
when adding your initial passphrase.cryptsetup convert --type luks2
. You can do this from the initrd if you use the GRUB shell to add the Linux command line parameter break
to drop you into busybox during the boot process.Your system should now be ready to install the EFI measured boot software stack.
sudo make install
Then follow further instructions from the install.
Eventually, I intend to turn this into an official Debian package, though manual steps to prep the system will likely still be required. While it is technically possible to automate the migration to an encrypted root with LUKS2 metadata, there are enough boot chain variations in Debian systems that a user who runs into an uncovered outlying failure case needs sufficient knowledge to be able to recover manually.
This project is heavily dependent on the work of Mantas Mikulėnas to parse the UEFI boot log in order to predict future PCR values.
This work is licensed under the MIT License. See the LICENSE file for more information.