uefi-md5sum - MD5 checksum validation for UEFI

Description

uefi-md5sum is a UEFI bootloader designed to perform MD5 hash verification of a
media containing an md5sum.txt list of hashes.

This is primarily aimed at being used with Rufus for the
creation of USB bootable media (such as Linux or Windows installation drives)
that can perform self-verification on each boot.

The reasoning with wanting to perform validation on boot rather than on media
creation is based on the fact that flash based media, and especially cheap USB
flash drives or SD cards, are exceedingly prone to failures after the media
was written.

As such, we assert that, only validating the content at write-time (like
balenaEtcher and, in part, Microsoft's Media Creation Tool do) is not enough to
help users ensure that their installation media hasn't become compromised.

This boot time validation can also prove itself useful if the boot process or
installation process produces errors, in which case, the first thing a user
may want to do, is reboot and let uefi-md5sum perform its check, to highlight
or rule out data corruption.

Usage

uefi-md5sum is intended to replace, and then chain load, the original UEFI
bootloader.

To accomplish this, the original /efi/boot/boot###.efi should be renamed to
/efi/boot/boot###_original.efi with uefi-md5sum bootloader then installed as
/efi/boot/boot###.efi.

md5sum.txt extensions

If md5sum.txt sets an md5sum_totalbytes variable, in the form of a comment
similar to:

# md5sum_totalbytes = 0x1234abcd

Then uefi-md5sum interprets this value to be sum of all the file sizes of the
files referenced in md5sum.txt, and uses it for more accurate progress
reporting. Otherwise, progress is only incremented after each file has been
processed, regardless of its actual size.

Thus, the provision of md5sum_totalbytes allows for accurate progress report,
as well the avoidance of apparent progress "freezeouts" when very large files
are being hashed (such as large squashfs or install.wim images).

It should be noted however that, currently, uefi-md5sum supports only the
provision of an md5sum_totalbytes value in hexadecimal (no decimal values).
On the other hand, there is no restriction to where, in md5sum.txt,
md5sum_totalbytes needs to be specified (i.e. it does not necessarily need to
appear at the beginning of the file).

md5sum.txt generation

On Linux, it is very easy to generate an md5sum.txt, that also includes
md5sum_totalbytes, by navigating to the directory that contains your content
and then issuing:

find . ! -name 'md5sum.txt' -type f -exec du -cb {} + | grep total$ | cut -f 1 | xargs printf '# md5sum_totalbytes = 0x%x\n' > md5sum.txt
find . ! -name 'md5sum.txt' -type f -exec md5sum {} \; >> md5sum.txt

Prerequisites

Visual Studio 2022 or gcc/EDK2.
QEMU v2.7 or later
(NB: You can find QEMU Windows binaries here)

Compilation

If using the Visual Studio solution (.sln), just press <kbd>F5</kbd> to
have the application compiled and launched in the QEMU emulator. Remember
however that you may first have to initialize the gnu-efi git submodules.

If using gcc with EDK2 on Linux, and assuming that your edk2 directory resides
in /usr/src/edk2:

  export EDK2_PATH="/usr/src/edk2"
  export WORKSPACE=$PWD
  export PACKAGES_PATH=$WORKSPACE:$EDK2_PATH
  . $EDK2_PATH/edksetup.sh --reconfig
  build -a X64 -b RELEASE -t GCC5 -p uefi-md5sum.dsc

Testing

The automated GitHub Actions build process is designed to run a very
comprehensive list of tests under QEMU. You can find a detailed summary of
all the tests being run in tests/test_list.txt.

README