efi_shim.c File Reference

UEFI shim special handling. More...

#include <string.h>
#include <stdlib.h>
#include <errno.h>
#include <ipxe/image.h>
#include <ipxe/efi/efi.h>
#include <ipxe/efi/efi_strings.h>
#include <ipxe/efi/efi_shim.h>
#include <ipxe/efi/Protocol/PxeBaseCode.h>
#include <ipxe/efi/Protocol/ShimLock.h>

Go to the source code of this file.

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
static int	efi_shim_is_sbatlevel (const CHAR16 *name, const EFI_GUID *guid)
	Check if variable is SbatLevel. More...
static void	efi_shim_unlock (void)
	Unlock UEFI shim. More...
static EFI_STATUS EFIAPI	efi_shim_set_variable (CHAR16 *name, EFI_GUID *guid, UINT32 attrs, UINTN len, VOID *data)
	Wrap SetVariable() More...
static EFI_STATUS EFIAPI	efi_shim_get_variable (CHAR16 *name, EFI_GUID *guid, UINT32 *attrs, UINTN *len, VOID *data)
	Wrap GetVariable() More...
static EFIAPI EFI_STATUS	efi_shim_get_memory_map (UINTN *len, EFI_MEMORY_DESCRIPTOR *map, UINTN *key, UINTN *desclen, UINT32 *descver)
	Wrap GetMemoryMap() More...
static int	efi_shim_inhibit_pxe (EFI_HANDLE handle)
	Inhibit use of PXE base code. More...
static int	efi_shim_cmdline (struct image *shim, wchar_t **cmdline)
	Update command line. More...
int	efi_shim_install (struct image *shim, EFI_HANDLE handle, wchar_t **cmdline)
	Install UEFI shim special handling. More...
void	efi_shim_uninstall (void)
	Uninstall UEFI shim special handling. More...

Variables
int	efi_shim_require_loader = 0
	Require use of a third party loader binary. More...
int	efi_shim_allow_pxe = 0
	Allow use of PXE base code protocol. More...
int	efi_shim_allow_sbat = 0
	Allow SBAT variable access. More...
struct image_tag efi_shim	__image_tag
	UEFI shim image. More...
static EFI_GET_MEMORY_MAP	efi_shim_orig_get_memory_map
	Original GetMemoryMap() function. More...
static EFI_SET_VARIABLE	efi_shim_orig_set_variable
	Original SetVariable() function. More...
static EFI_GET_VARIABLE	efi_shim_orig_get_variable
	Original GetVariable() function. More...
static int	efi_shim_sbatlevel_verify
	Verify read from SbatLevel variable. More...

Detailed Description

UEFI shim special handling.

Definition in file efi_shim.c.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

efi_shim_is_sbatlevel()

static int efi_shim_is_sbatlevel ( const CHAR16 *  name, const EFI_GUID *  guid  )

static

Check if variable is SbatLevel.

Parameters

name	Variable name
guid	Variable namespace GUID

Return values

is_sbatlevel

Variable is SbatLevel

Definition at line 131 of file efi_shim.c.

                                                                              {
        static CHAR16 sbatlevel[] = L"SbatLevel";
        EFI_GUID *shimlock = &efi_shim_lock_protocol_guid;

        return ( ( memcmp ( name, sbatlevel, sizeof ( sbatlevel ) ) == 0 ) &&
                 ( memcmp ( guid, shimlock, sizeof ( *shimlock ) ) == 0 ) );
}

References efi_shim_lock_protocol_guid, guid, memcmp(), and name.

Referenced by efi_shim_get_variable(), and efi_shim_set_variable().

efi_shim_unlock()

static void efi_shim_unlock ( void  )

static

Unlock UEFI shim.

Definition at line 143 of file efi_shim.c.

                                     {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        uint8_t empty[0];
        union {
                EFI_SHIM_LOCK_PROTOCOL *lock;
                void *interface;
        } u;
        EFI_STATUS efirc;

        /* Locate shim lock protocol */
        if ( ( efirc = bs->LocateProtocol ( &efi_shim_lock_protocol_guid,
                                            NULL, &u.interface ) ) == 0 ) {
                u.lock->Verify ( empty, sizeof ( empty ) );
                DBGC ( &efi_shim, "SHIM unlocked via %p\n", u.lock );
        }
}

References EFI_SYSTEM_TABLE::BootServices, DBGC, efi_shim_lock_protocol_guid, efi_systab, EFI_BOOT_SERVICES::LocateProtocol, NULL, and u.

Referenced by efi_shim_get_memory_map().

efi_shim_set_variable()

static EFI_STATUS EFIAPI efi_shim_set_variable ( CHAR16 *  name, EFI_GUID *  guid, UINT32  attrs, UINTN  len, VOID *  data  )

static

Wrap SetVariable()

Parameters

name	Variable name
guid	Variable namespace GUID
attrs	Attributes
len	Buffer size
data	Data buffer

Return values

efirc

EFI status code

Definition at line 171 of file efi_shim.c.

                                                {
        EFI_STATUS efirc;

        /* Call original SetVariable() */
        efirc = efi_shim_orig_set_variable ( name, guid, attrs, len, data );

        /* Allow verification of SbatLevel variable content */
        if ( efi_shim_is_sbatlevel ( name, guid ) && ( efirc == 0 ) ) {
                DBGC ( &efi_shim, "SHIM detected write to %ls:\n", name );
                DBGC_HDA ( &efi_shim, 0, data, len );
                efi_shim_sbatlevel_verify = 1;
        }

        return efirc;
}

References attrs, data, DBGC, DBGC_HDA, efi_shim_is_sbatlevel(), efi_shim_orig_set_variable, efi_shim_sbatlevel_verify, guid, len, and name.

Referenced by efi_shim_get_memory_map(), and efi_shim_install().

efi_shim_get_variable()

static EFI_STATUS EFIAPI efi_shim_get_variable ( CHAR16 *  name, EFI_GUID *  guid, UINT32 *  attrs, UINTN *  len, VOID *  data  )

static

Wrap GetVariable()

Parameters

name	Variable name
guid	Variable namespace GUID
attrs	Attributes to fill in
len	Buffer size
data	Data buffer

Return values

efirc

EFI status code

Definition at line 199 of file efi_shim.c.

                                                 {
        char *value = data;
        EFI_STATUS efirc;

        /* Call original GetVariable() */
        efirc = efi_shim_orig_get_variable ( name, guid, attrs, len, data );

        /* Patch SbatLevel variable if applicable */
        if ( efi_shim_is_sbatlevel ( name, guid ) && data && ( efirc == 0 ) ) {
                if ( efi_shim_allow_sbat ) {
                        DBGC ( &efi_shim, "SHIM allowing read from %ls:\n",
                               name );
                } else if ( efi_shim_sbatlevel_verify ) {
                        DBGC ( &efi_shim, "SHIM allowing one read from %ls:\n",
                               name );
                        efi_shim_sbatlevel_verify = 0;
                } else {
                        DBGC ( &efi_shim, "SHIM patching read from %ls:\n",
                               name );
                        value[0] = '\0';
                }
                DBGC_HDA ( &efi_shim, 0, data, *len );
        }

        return efirc;
}

References attrs, data, DBGC, DBGC_HDA, efi_shim_allow_sbat, efi_shim_is_sbatlevel(), efi_shim_orig_get_variable, efi_shim_sbatlevel_verify, guid, len, name, and value.

Referenced by efi_shim_get_memory_map(), and efi_shim_install().

efi_shim_get_memory_map()

static EFIAPI EFI_STATUS efi_shim_get_memory_map ( UINTN *  len, EFI_MEMORY_DESCRIPTOR *  map, UINTN *  key, UINTN *  desclen, UINT32 *  descver  )

static

Wrap GetMemoryMap()

Parameters

len	Memory map size
map	Memory map
key	Memory map key
desclen	Descriptor size
descver	Descriptor version

Return values

efirc

EFI status code

Definition at line 237 of file efi_shim.c.

                                                                     {
        EFI_RUNTIME_SERVICES *rs = efi_systab->RuntimeServices;

        /* Unlock shim */
        if ( ! efi_shim_require_loader )
                efi_shim_unlock();

        /* Uninstall runtime services wrappers, if still installed */
        if ( rs->SetVariable == efi_shim_set_variable ) {
                rs->SetVariable = efi_shim_orig_set_variable;
                DBGC ( &efi_shim, "SHIM uninstalled SetVariable() wrapper\n" );
        } else if ( rs->SetVariable != efi_shim_orig_set_variable ) {
                DBGC ( &efi_shim, "SHIM could not uninstall SetVariable() "
                       "wrapper!\n" );
        }
        if ( rs->GetVariable == efi_shim_get_variable ) {
                rs->GetVariable = efi_shim_orig_get_variable;
                DBGC ( &efi_shim, "SHIM uninstalled GetVariable() wrapper\n" );
        } else if ( rs->GetVariable != efi_shim_orig_get_variable ) {
                DBGC ( &efi_shim, "SHIM could not uninstall GetVariable() "
                       "wrapper!\n" );
        }

        /* Hand off to original GetMemoryMap() */
        return efi_shim_orig_get_memory_map ( len, map, key, desclen,
                                              descver );
}

References DBGC, efi_shim_get_variable(), efi_shim_orig_get_memory_map, efi_shim_orig_get_variable, efi_shim_orig_set_variable, efi_shim_require_loader, efi_shim_set_variable(), efi_shim_unlock(), efi_systab, EFI_RUNTIME_SERVICES::GetVariable, key, len, map, EFI_SYSTEM_TABLE::RuntimeServices, and EFI_RUNTIME_SERVICES::SetVariable.

Referenced by efi_shim_install().

efi_shim_inhibit_pxe()

static int efi_shim_inhibit_pxe ( EFI_HANDLE  handle )

static

Inhibit use of PXE base code.

Parameters

handle

EFI handle

Return values

rc	Return status code

Definition at line 274 of file efi_shim.c.

                                                      {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        union {
                EFI_PXE_BASE_CODE_PROTOCOL *pxe;
                void *interface;
        } u;
        EFI_STATUS efirc;
        int rc;

        /* Locate PXE base code */
        if ( ( efirc = bs->OpenProtocol ( handle,
                                          &efi_pxe_base_code_protocol_guid,
                                          &u.interface, efi_image_handle, NULL,
                                          EFI_OPEN_PROTOCOL_GET_PROTOCOL ))!=0){
                rc = -EEFI ( efirc );
                DBGC ( &efi_shim, "SHIM could not open PXE base code: %s\n",
                       strerror ( rc ) );
                goto err_no_base;
        }

        /* Stop PXE base code */
        if ( ( efirc = u.pxe->Stop ( u.pxe ) ) != 0 ) {
                rc = -EEFI ( efirc );
                DBGC ( &efi_shim, "SHIM could not stop PXE base code: %s\n",
                       strerror ( rc ) );
                goto err_stop;
        }

        /* Success */
        rc = 0;
        DBGC ( &efi_shim, "SHIM stopped PXE base code\n" );

 err_stop:
        bs->CloseProtocol ( handle, &efi_pxe_base_code_protocol_guid,
                            efi_image_handle, NULL );
 err_no_base:
        return rc;
}

References EFI_SYSTEM_TABLE::BootServices, EFI_BOOT_SERVICES::CloseProtocol, DBGC, EEFI, efi_image_handle, EFI_OPEN_PROTOCOL_GET_PROTOCOL, efi_pxe_base_code_protocol_guid, efi_systab, handle, NULL, EFI_BOOT_SERVICES::OpenProtocol, rc, strerror(), and u.

Referenced by efi_shim_install().

efi_shim_cmdline()

static int efi_shim_cmdline ( struct image *  shim, wchar_t **  cmdline  )

static

Update command line.

Parameters

shim	Shim image
cmdline	Command line to update

Return values

rc	Return status code

Definition at line 320 of file efi_shim.c.

                                                                      {
        wchar_t *shimcmdline;
        int len;
        int rc;

        /* Construct new command line */
        len = ( shim->cmdline ?
                efi_asprintf ( &shimcmdline, "%s %s", shim->name,
                               shim->cmdline ) :
                efi_asprintf ( &shimcmdline, "%s %ls", shim->name,
                               *cmdline ) );
        if ( len < 0 ) {
                rc = len;
                DBGC ( &efi_shim, "SHIM could not construct command line: "
                       "%s\n", strerror ( rc ) );
                return rc;
        }

        /* Replace command line */
        free ( *cmdline );
        *cmdline = shimcmdline;

        return 0;
}

References cmdline, DBGC, efi_asprintf(), free, len, rc, shim(), and strerror().

Referenced by efi_shim_install().

efi_shim_install()

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

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 353 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 EFI_SYSTEM_TABLE::BootServices, cmdline, DBGC, 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_SYSTEM_TABLE::RuntimeServices, EFI_RUNTIME_SERVICES::SetVariable, and shim().

Referenced by efi_image_exec().

efi_shim_uninstall()

void efi_shim_uninstall

(

void

)

Uninstall UEFI shim special handling.

Definition at line 387 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 EFI_SYSTEM_TABLE::BootServices, 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, EFI_SYSTEM_TABLE::RuntimeServices, and EFI_RUNTIME_SERVICES::SetVariable.

Referenced by efi_image_exec().

Variable Documentation

efi_shim_require_loader

int efi_shim_require_loader = 0

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 67 of file efi_shim.c.

Referenced by efi_shim_get_memory_map(), and shim().

efi_shim_allow_pxe

int efi_shim_allow_pxe = 0

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 85 of file efi_shim.c.

Referenced by efi_shim_install(), and shim().

efi_shim_allow_sbat

int efi_shim_allow_sbat = 0

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 105 of file efi_shim.c.

Referenced by efi_shim_get_variable(), and shim().

__image_tag

struct image_tag efi_shim __image_tag

Initial value:

= {
        .name = "SHIM",
}

UEFI shim image.

Image selected for execution.

Definition at line 108 of file efi_shim.c.

efi_shim_orig_get_memory_map

EFI_GET_MEMORY_MAP efi_shim_orig_get_memory_map

static

Original GetMemoryMap() function.

Definition at line 113 of file efi_shim.c.

Referenced by efi_shim_get_memory_map(), efi_shim_install(), and efi_shim_uninstall().

efi_shim_orig_set_variable

EFI_SET_VARIABLE efi_shim_orig_set_variable

static

Original SetVariable() function.

Definition at line 116 of file efi_shim.c.

Referenced by efi_shim_get_memory_map(), efi_shim_install(), efi_shim_set_variable(), and efi_shim_uninstall().

efi_shim_orig_get_variable

EFI_GET_VARIABLE efi_shim_orig_get_variable

static

Original GetVariable() function.

Definition at line 119 of file efi_shim.c.

Referenced by efi_shim_get_memory_map(), efi_shim_get_variable(), efi_shim_install(), and efi_shim_uninstall().

efi_shim_sbatlevel_verify

int efi_shim_sbatlevel_verify

static

Verify read from SbatLevel variable.

Definition at line 122 of file efi_shim.c.

Referenced by efi_shim_get_variable(), and efi_shim_set_variable().