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 F5 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.