Appendix: Patch GRUB 2.12/2.06 to Add LUKS2 and Argon2 Support

3 minutes to read

At the time of writing, the latest release of GRUB, which is 2.14, has built-in LUKS2 and Argon2id support. Therefore, users who can use the latest GRUB release do not need to patch its source code to add LUKS2 and Argon2 support, hence they can ignore the information on this page.

However, users of older GRUB releases, including 2.12 and 2.06, need to patch them. Neither GRUB 2.12 nor GRUB 2.06 has built-in support for Argon2id; GRUB 2.06 even has more limitations on LUKS2 support. Therefore, both GRUB 2.12 and GRUB 2.06 need some patches for LUKS2 and Argon2 support.

GRUB 2.12

GRUB 2.12 only needs one patch grub-2.12-luks2-argon2-v4.patch to get support for LUKS2 with Argon2. This patch was originally submitted to the grub-devel mailing list and targeted GRUB 2.06; I ported it to GRUB 2.12, and it still works.

To apply this patch to Gentoo’s GRUB package – sys-boot/grub, add it as a Portage user patch to /etc/portage/patches/sys-boot/grub-2.12. Patches at this location are applied to all Gentoo revisions of GRUB 2.12 (-r1, -r2, etc.). The following commands may be used to do this:

# mkdir -p /etc/portage/patches/sys-boot/grub-2.12
# cd /etc/portage/patches/sys-boot/grub-2.12
# curl -O https://leo3418.github.io/res/collections/gentoo-config-luks2-grub-systemd/grub-2.12-luks2-argon2-v4.patch

Readers who are interested in learning more about Portage’s user patch feature are welcome to read another article on this website that discusses it in depth.

Because this patch modifies the file grub-core/Makefile.core.def, according to the sys-boot/grub ebuild, the GRUB_AUTOGEN and GRUB_AUTORECONF environment variables must be set. Otherwise, any builds of the package with the patch applied would fail. The environment variable can be set exclusively for all Gentoo revisions of sys-boot/grub-2.12 in file /etc/portage/env/sys-boot/grub-2.12:

# mkdir -p /etc/portage/env/sys-boot
# echo -e 'GRUB_AUTOGEN=1\nGRUB_AUTORECONF=1' >> /etc/portage/env/sys-boot/grub-2.12

GRUB 2.06

GRUB 2.06’s support for LUKS2 is more limited. Although code implementing partial LUKS2 support exists in this version, the bootloader files installed using the default procedure do not support LUKS2.

Luckily, after applying the following patches to GRUB 2.06, LUKS2 support can be added to the installed bootloader files automatically, and Argon2id is supported too.

  • 4500-grub-2.06-runtime-memregion-alloc.patch: A patch set that allows GRUB to allocate new consecutive and large memory chunks, which is a prerequisite for Argon2 support in GRUB. Argon2 enhances the security of LUKS by increasing the size of memory required for unlocking computations, so GRUB must be able to allocate more memory when needed. This patch set was cherry-picked from GRUB 2.12.

  • 5000-grub-2.06-luks2-argon2-v4.patch: The patch set that adds Argon2 support itself to GRUB. This patch is equivalent to the only patch needed for GRUB 2.12 mentioned above.

  • 9500-grub-AUR-improved-luks2.patch: A patch included in the grub-improved-luks2-git package on the AUR, which is what the Arch Wiki’s GRUB article recommends for users seeking great LUKS2 support in GRUB. This patch allows GRUB 2.06’s grub-install command to automatically install bootloader files with LUKS2 support.

The numbers in front of the patches’ file names are there only to control the order in which they are applied (patches with a smaller ordinal are applied first). As long as the order is maintained, these numbers’ values are arbitrary.

Similar to the case of GRUB 2.12, add these patches as Portage user patches to /etc/portage/patches/sys-boot/grub-2.06:

# mkdir -p /etc/portage/patches/sys-boot/grub-2.06
# cd /etc/portage/patches/sys-boot/grub-2.06
# curl -O https://leo3418.github.io/res/collections/gentoo-config-luks2-grub-systemd/4500-grub-2.06-runtime-memregion-alloc.patch
# curl -O https://leo3418.github.io/res/collections/gentoo-config-luks2-grub-systemd/5000-grub-2.06-luks2-argon2-v4.patch
# curl -O https://leo3418.github.io/res/collections/gentoo-config-luks2-grub-systemd/9500-grub-AUR-improved-luks2.patch

Then, add the required environment variables to /etc/portage/env/sys-boot/grub-2.06:

# mkdir -p /etc/portage/env/sys-boot
# echo -e 'GRUB_AUTOGEN=1\nGRUB_AUTORECONF=1' >> /etc/portage/env/sys-boot/grub-2.06