efi_shim.h File Reference

UEFI shim special handling. More...

#include <ipxe/image.h>
#include <ipxe/efi/efi.h>

Go to the source code of this file.

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
int	efi_shim_install (struct image *shim, EFI_HANDLE handle, wchar_t **cmdline)
	Install UEFI shim special handling.
void	efi_shim_uninstall (void)
	Uninstall UEFI shim special handling.

Variables
int	efi_shim_require_loader
	Require use of a third party loader binary.
int	efi_shim_allow_pxe
	Allow use of PXE base code protocol.
int	efi_shim_allow_sbat
	Allow SBAT variable access.
struct image_tag efi_shim	__image_tag
	The downloaded flattened device tree tag.

Detailed Description

UEFI shim special handling.

Definition in file efi_shim.h.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

References __image_tag, cmdline, EFI_HANDLE, efi_shim_allow_pxe, efi_shim_allow_sbat, efi_shim_require_loader, handle, and shim().

efi_shim_install()

int efi_shim_install ( struct image * shim, EFI_HANDLE handle, wchar_t ** cmdline )

extern

Install UEFI shim special handling.

Parameters

shim	Shim image
handle	EFI device handle
cmdline	Command line to update

Return values

rc	Return status code

Definition at line 366 of file efi_shim.c.

                                           {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_RUNTIME_SERVICES *rs = efi_systab->RuntimeServices;
        int rc;
 
        /* Stop PXE base code */
        if ( ( ! efi_shim_allow_pxe ) &&
             ( ( rc = efi_shim_inhibit_pxe ( handle ) ) != 0 ) ) {
                return rc;
        }
 
        /* Update command line */
        if ( ( rc = efi_shim_cmdline ( shim, cmdline ) ) != 0 )
                return rc;
 
        /* Record original boot and runtime services functions */
        efi_shim_orig_get_memory_map = bs->GetMemoryMap;
        efi_shim_orig_set_variable = rs->SetVariable;
        efi_shim_orig_get_variable = rs->GetVariable;
 
        /* Wrap relevant boot and runtime services functions */
        bs->GetMemoryMap = efi_shim_get_memory_map;
        rs->SetVariable = efi_shim_set_variable;
        rs->GetVariable = efi_shim_get_variable;
        DBGC ( &efi_shim, "SHIM installed wrappers\n" );
 
        return 0;
}

References cmdline, DBGC, EFI_HANDLE, efi_shim_allow_pxe, efi_shim_cmdline(), efi_shim_get_memory_map(), efi_shim_get_variable(), efi_shim_inhibit_pxe(), efi_shim_orig_get_memory_map, efi_shim_orig_get_variable, efi_shim_orig_set_variable, efi_shim_set_variable(), efi_systab, EFI_BOOT_SERVICES::GetMemoryMap, EFI_RUNTIME_SERVICES::GetVariable, handle, rc, EFI_RUNTIME_SERVICES::SetVariable, and shim().

Referenced by efi_image_exec().

efi_shim_uninstall()

void efi_shim_uninstall ( void )

extern

Uninstall UEFI shim special handling.

Definition at line 400 of file efi_shim.c.

                                 {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_RUNTIME_SERVICES *rs = efi_systab->RuntimeServices;
 
        /* Restore original boot and runtime services functions */
        bs->GetMemoryMap = efi_shim_orig_get_memory_map;
        rs->SetVariable = efi_shim_orig_set_variable;
        rs->GetVariable = efi_shim_orig_get_variable;
        DBGC ( &efi_shim, "SHIM uninstalled wrappers\n" );
}

References DBGC, efi_shim_orig_get_memory_map, efi_shim_orig_get_variable, efi_shim_orig_set_variable, efi_systab, EFI_BOOT_SERVICES::GetMemoryMap, EFI_RUNTIME_SERVICES::GetVariable, and EFI_RUNTIME_SERVICES::SetVariable.

Referenced by efi_image_exec().

Variable Documentation

efi_shim_require_loader

int efi_shim_require_loader

extern

Require use of a third party loader binary.

The UEFI shim is gradually becoming less capable of directly executing a Linux kernel image, due to an ever increasing list of assumptions that it will only ever be used in conjunction with a second stage loader binary such as GRUB.

For example: shim will erroneously complain if the image that it loads and executes does not in turn call in to the "shim lock protocol" to verify a separate newly loaded binary before calling ExitBootServices(), even if no such separate binary is used or required.

Experience shows that there is unfortunately no point in trying to get a fix for this upstreamed into shim. We therefore default to reducing the Secure Boot attack surface by removing, where possible, this spurious requirement for the use of an additional second stage loader.

This option may be used to require the use of an additional second stage loader binary, in case this behaviour is ever desirable.

Definition at line 69 of file efi_shim.c.

Referenced by efi_shim_get_memory_map(), FILE_SECBOOT(), and shim().

efi_shim_allow_pxe

int efi_shim_allow_pxe

extern

Allow use of PXE base code protocol.

We provide shim with access to all of the relevant downloaded files via our EFI_SIMPLE_FILE_SYSTEM_PROTOCOL interface. However, shim will instead try to redownload the files via TFTP since it prefers to use the EFI_PXE_BASE_CODE_PROTOCOL installed on the same handle.

Experience shows that there is unfortunately no point in trying to get a fix for this upstreamed into shim. We therefore default to working around this undesirable behaviour by stopping the PXE base code protocol before invoking shim.

This option may be used to allow shim to use the PXE base code protocol, in case this behaviour is ever desirable.

Definition at line 87 of file efi_shim.c.

Referenced by efi_shim_install(), FILE_SECBOOT(), and shim().

efi_shim_allow_sbat

int efi_shim_allow_sbat

extern

Allow SBAT variable access.

The UEFI shim implements a fairly nicely designed revocation mechanism designed around the concept of security generations. Unfortunately nobody in the shim community has thus far added the relevant metadata to the Linux kernel, with the result that current versions of shim are incapable of booting current versions of the Linux kernel.

Experience shows that there is unfortunately no point in trying to get a fix for this upstreamed into shim. We therefore default to working around this undesirable behaviour by patching data read from the "SbatLevel" variable used to hold SBAT configuration.

This option may be used to allow shim unpatched access to the "SbatLevel" variable, in case this behaviour is ever desirable.

Definition at line 107 of file efi_shim.c.

Referenced by efi_shim_get_variable(), FILE_SECBOOT(), and shim().

__image_tag

struct image_tag efi_shim __image_tag

extern

The downloaded flattened device tree tag.

The downloaded flattened device tree tag.

Currently-executing image.

The downloaded flattened device tree tag.

Definition at line 48 of file fdt.c.

                                         {
        .name = "FDT",
};