From Gentoo Wiki
Jump to:navigation Jump to:search

Shim is an alternative method of managing accepted Secure Boot keys without touching the UEFI firmware settings


The global secureboot USE flag can be enabled to automatically sign any EFI executables installed by a package. To use this flag the SECUREBOOT_SIGN_KEY and SECUREBOOT_SIGN_CERT user variables must be set in make.conf and point to a valid PEM format OpenSSL key (or PKCS11 URI) and certificate respectively.

Generating keys

The procedure for generating a new OpenSSL key/certificate pair is documented on the Secure Boot page. Note that when shim is used only one key (called the Machine Owner Key) is required. Since Shim is already signed by the 3rd-party Microsoft certificate accepted by default on most motherboards there is no need to create and manage a Platform Key, Key Exchange Key, or the (forbidden) Signature Database.

The key that was used to sign the kernel modules may also be used as the Machine Owner Key to sign the boot files.


The sys-boot/shim package provides a pre-compiled version of shim distributed by Fedora and pre-signed with the 3rd-party Microsoft certificate. This Microsoft certificate is accepted by default on most UEFI-enabled motherboards, this allows users to delegate secure boot key management to shim without having to touch the firmware's default UEFI Secure Boot keys.

The sys-boot/mokutil package makes it possible to manage shim's Machine Owner Key (MOK) list from within the Linux operating system.

Install both with:

root #emerge sys-boot/shim sys-boot/mokutil


For shim to be able to verify the signed boot files it must be loaded before the boot loader. Unfortunately the shim distributed by Fedora is hard coded to load GRUB. To use other boot loaders the boot loader EFI file must be renamed to grubx64.efi (where x64 will need to be adjusted for architectures other then amd64). The detailed process for each supported boot loader is outlined below.

After the steps for the chosen boot loader have been followed, the systems boot order must be adjusted to load shim first instead of the boot loader. Either use efibootmgr or the system's UEFI firmware interface.


For shim to successfully load GRUB, GRUB must be installed with a Secure Boot Advanced Targeting (SBAT) section embedded into the EFI file. A sample SBAT is available at /usr/share/grub/sbat.csv, edit it and re-install GRUB:

root #grub-install ... --sbat /usr/share/grub/sbat.csv

Copy shim and the MokManager to the same directory on the EFI System Partition that currently holds the grubx64.efi. For example if the grubx64.efi is located at /boot/EFI/gentoo/grubx64.efi:

root #cp /usr/share/shim/BOOTX64.EFI /boot/EFI/Gentoo/shimx64.efi
root #cp /usr/share/shim/mmx64.efi /boot/EFI/Gentoo/mmx64.efi

If GRUB was installed with the --removable flag it will be located at EFI/BOOT/BOOTX64.EFI on the EFI System Partition. In this case it must first be renamed to grubx64.efi:

root #mv /boot/EFI/BOOT/BOOTX64.EFI /boot/EFI/BOOT/grubx64.efi
root #cp /usr/share/shim/BOOTX64.EFI /boot/EFI/BOOT/BOOTX64.EFI
root #cp /usr/share/shim/mmx64.efi /boot/EFI/BOOT/mmx64.efi

Because the GRUB efi file is compiled by grub-install it has not yet been signed by portage. Sign it manually with app-crypt/sbsigntools where SECUREBOOT_SIGN_KEY and SECUREBOOT_SIGN_CERT should be replaced with your respective key and certificate:

root #sbsign --key ${SECUREBOOT_SIGN_KEY} --cert ${SECUREBOOT_SIGN_CERT} --output /boot/EFI/gentoo/grubx64.efi /boot/EFI/gentoo/grubx64.efi

If SECUREBOOT_SIGN_KEY is a PKCS11 URI the --engine pkcs11 argument has to be added.

If GRUB was installed with shim-lock enabled (the default) it is not allowed to load additional modules when Secure Boot is enabled. Either disable the shim-lock (grub-install ... --disable-shim-lock) or compile all the modules that should be available into the GRUB EFI executable (grub-install ... --modules=...).


A postinst hook to automatically setup shim with systemd-boot is available. The systemd-boot EFI file is already signed if USE=secureboot is enabled.


To setup rEFInd with shim:

root #refind-install ... --shim /usr/share/shim/BOOTX64.EFI ...

The rEFInd efi file is already signed if USE=secureboot is enabled.

Signing the kernel

The Distribution Kernels are automatically signed if USE=secureboot is enabled. If a manually configured and compiled kernel is used instead it must be manually signed using app-crypt/sbsigntools where SECUREBOOT_SIGN_KEY and SECUREBOOT_SIGN_CERT should be replaced with your respective key and certificate:

root #sbsign --key ${SECUREBOOT_SIGN_KEY} --cert ${SECUREBOOT_SIGN_CERT} --output /boot/EFI/gentoo/linux-x.y.z-gentoo.efi /boot/EFI/gentoo/linux-x.y.z-gentoo.efi

If SECUREBOOT_SIGN_KEY is a PKCS11 URI the --engine pkcs11 argument has to be added.

Managing the MOK list

To successfully boot with Secure Boot enabled the used SECUREBOOT_SIGN_CERT should be added to the MOK list. Unfortunately while sbsign requires keys and certificates in PEM format, the MOK list requires the certificate in DER format. Therefore the certificate must first be converted to DER format:

root #openssl x509 -inform pem -in ${SECUREBOOT_SIGN_CERT} -outform der -out /boot/sbcert.der

An import request for shim can be generated with:

root #mokutil --import /boot/sbcert.der

Next reboot, shim will find that there is a pending import request and launch MokManager. Enter the password and complete the import process.

Signed kernel modules

To successfully boot with Secure Boot enabled the kernel modules must be signed as well. The kernel build system automatically embeds the certificate that was used to sign the modules into the kernel image, as such it is not required to import this certificate into the MOK list. If however some kernel modules are signed with a different key then was used when building the kernel, then the accompanying certificate must also be imported into the MOK list. This situation may occur when a pre-compiled kernel binpkg was installed (e.g. sys-kernel/gentoo-kernel-bin) as well as one or more external third-party modules. The original key that was used for the kernel binpkg may not be available on this system, and as such the external third-party modules will have to be signed with a different key.

Valid signatures on modules can be enforced with the module.sig_enforce=1 kernel command line argument. This is the default for sys-kernel/gentoo-kernel and sys-kernel/vanilla-kernel if the secureboot USE flag is enabled, but it is not the default for sys-kernel/gentoo-kernel-bin.

See also

  • UEFI — a firmware standard for boot ROM designed to provide a stable API for interacting with system hardware. On x86 it replaced the legacy BIOS.
  • Efibootmgr — a tool for managing UEFI boot entries.
  • Secure Boot — an enhancement the security of the pre-boot process of a UEFI system.
  • EFI stub — describes EFI stub kernels, i.e. kernels directly executable from UEFI.