Functions
EFI_STATUS EFIAPI	SetSecureBootMode (IN UINT8 SecureBootMode)

EFI_STATUS EFIAPI	GetSetupMode (OUT UINT8 *SetupMode)

BOOLEAN EFIAPI	IsSecureBootEnabled (VOID)

EFI_STATUS EFIAPI	SecureBootCreateDataFromInput (OUT UINTN SigListsSize, OUT EFI_SIGNATURE_LIST SigListOut, IN UINTN KeyInfoCount, IN CONST SECURE_BOOT_CERTIFICATE_INFO KeyInfo)

EFI_STATUS EFIAPI	CreateTimeBasedPayload (IN OUT UINTN DataSize, IN OUT UINT8 Data, IN EFI_TIME Time)

EFI_STATUS EFIAPI	DeleteDb (VOID)

EFI_STATUS EFIAPI	DeleteDbx (VOID)

EFI_STATUS EFIAPI	DeleteDbt (VOID)

EFI_STATUS EFIAPI	DeleteKEK (VOID)

EFI_STATUS EFIAPI	DeletePlatformKey (VOID)

EFI_STATUS EFIAPI	DeleteSecureBootVariables (VOID)

EFI_STATUS EFIAPI	EnrollFromInput (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, IN UINTN DataSize, IN VOID *Data)

EFI_STATUS EFIAPI	SetSecureBootVariablesToDefault (IN CONST SECURE_BOOT_PAYLOAD_INFO *SecureBootPayload)

Detailed Description

Provides a helper functions for creating variable authenticated payloads, signature lists related to secure boot keys.

Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.
(C) Copyright 2018 Hewlett Packard Enterprise Development LP
Copyright (c) 2021, ARM Ltd. All rights reserved.
Copyright (c) 2021, Semihalf All rights reserved.
Copyright (c) Microsoft Corporation. SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file SecureBootVariableLib.h.

Function Documentation

◆ CreateTimeBasedPayload()

EFI_STATUS EFIAPI CreateTimeBasedPayload	(	IN OUT UINTN *	DataSize,
		IN OUT UINT8 **	Data,
		IN EFI_TIME *	Time
	)

Create a time based data payload by concatenating the EFI_VARIABLE_AUTHENTICATION_2 descriptor with the input data. NO authentication is required in this function.

Parameters

[in,out]	DataSize	On input, the size of Data buffer in bytes. On output, the size of data returned in Data buffer in bytes.
[in,out]	Data	On input, Pointer to data buffer to be wrapped or pointer to NULL to wrap an empty payload. On output, Pointer to the new payload date buffer allocated from pool, it's caller's responsibility to free the memory when finish using it.
[in]	Time	Pointer to time information to created time based payload.

Return values

EFI_SUCCESS	Create time based payload successfully.
EFI_OUT_OF_RESOURCES	There are not enough memory resources to create time based payload.
EFI_INVALID_PARAMETER	The parameter is invalid.
Others	Unexpected error happens.

Definition at line 266 of file SecureBootVariableLib.c.

◆ DeleteDb()

EFI_STATUS EFIAPI DeleteDb ( VOID )

Clears the content of the 'db' variable.

Return values

EFI_OUT_OF_RESOURCES

If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails while VendorGuid is NULL.

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

Clears the content of the 'db' variable.

Return values

EFI_OUT_OF_RESOURCES	If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails while VendorGuid is NULL.
other	Errors from GetVariable2 (), GetTime () and SetVariable ()

Definition at line 482 of file SecureBootVariableLib.c.

◆ DeleteDbt()

EFI_STATUS EFIAPI DeleteDbt ( VOID )

Clears the content of the 'dbt' variable.

Return values

EFI_OUT_OF_RESOURCES

If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails while VendorGuid is NULL.

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

Clears the content of the 'dbt' variable.

Return values

EFI_OUT_OF_RESOURCES	If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails while VendorGuid is NULL.
other	Errors from GetVariable2 (), GetTime () and SetVariable ()

Definition at line 528 of file SecureBootVariableLib.c.

◆ DeleteDbx()

EFI_STATUS EFIAPI DeleteDbx ( VOID )

Clears the content of the 'dbx' variable.

Return values

EFI_OUT_OF_RESOURCES

If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails while VendorGuid is NULL.

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

Clears the content of the 'dbx' variable.

Return values

EFI_OUT_OF_RESOURCES	If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails while VendorGuid is NULL.
other	Errors from GetVariable2 (), GetTime () and SetVariable ()

Definition at line 505 of file SecureBootVariableLib.c.

◆ DeleteKEK()

EFI_STATUS EFIAPI DeleteKEK ( VOID )

Clears the content of the 'KEK' variable.

Return values

EFI_OUT_OF_RESOURCES

If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails while VendorGuid is NULL.

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

Clears the content of the 'KEK' variable.

Return values

EFI_OUT_OF_RESOURCES	If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails while VendorGuid is NULL.
other	Errors from GetVariable2 (), GetTime () and SetVariable ()

Definition at line 551 of file SecureBootVariableLib.c.

◆ DeletePlatformKey()

EFI_STATUS EFIAPI DeletePlatformKey ( VOID )

Clears the content of the 'PK' variable.

Return values

EFI_OUT_OF_RESOURCES

If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails while VendorGuid is NULL.

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

Remove the PK variable.

Return values

EFI_SUCCESS	Delete PK successfully.
Others	Could not allow to delete PK.

Definition at line 574 of file SecureBootVariableLib.c.

◆ DeleteSecureBootVariables()

EFI_STATUS EFIAPI DeleteSecureBootVariables ( VOID )

This function will delete the secure boot keys, thus disabling secure boot.

Returns: EFI_SUCCESS or underlying failure code.

Definition at line 600 of file SecureBootVariableLib.c.

◆ EnrollFromInput()

EFI_STATUS EFIAPI EnrollFromInput	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		IN UINTN	DataSize,
		IN VOID *	Data
	)

A helper function to take in a variable payload, wrap it in the proper authenticated variable structure, and install it in the EFI variable space.

Parameters

[in]	VariableName	The name of the key/database.
[in]	VendorGuid	The namespace (ie. vendor GUID) of the variable
[in]	DataSize	Size parameter for target secure boot variable.
[in]	Data	Pointer to signature list formatted secure boot variable content.

Return values

EFI_SUCCESS	The enrollment for authenticated variable was successful.
EFI_OUT_OF_RESOURCES	There are not enough memory resources to create time based payload.
EFI_INVALID_PARAMETER	The parameter is invalid.
Others	Unexpected error happens.

Definition at line 693 of file SecureBootVariableLib.c.

◆ GetSetupMode()

EFI_STATUS EFIAPI GetSetupMode ( OUT UINT8 * SetupMode )

Fetches the value of SetupMode variable.

Parameters

[out] SetupMode Pointer to UINT8 for SetupMode output

@retval other Error codes from GetVariable.

Fetches the value of SetupMode variable.

Parameters

[out] SetupMode Pointer to UINT8 for SetupMode output

Return values

other Retval from GetVariable.

Definition at line 413 of file SecureBootVariableLib.c.

◆ IsSecureBootEnabled()

BOOLEAN EFIAPI IsSecureBootEnabled ( VOID )

Helper function to quickly determine whether SecureBoot is enabled.

Return values

TRUE	SecureBoot is verifiably enabled.
FALSE	SecureBoot is either disabled or an error prevented checking.

Definition at line 444 of file SecureBootVariableLib.c.

◆ SecureBootCreateDataFromInput()

EFI_STATUS EFIAPI SecureBootCreateDataFromInput	(	OUT UINTN *	SigListsSize,
		OUT EFI_SIGNATURE_LIST **	SigListOut,
		IN UINTN	KeyInfoCount,
		IN CONST SECURE_BOOT_CERTIFICATE_INFO *	KeyInfo
	)

Create a EFI Signature List with data supplied from input argument. The input certificates from KeyInfo parameter should be DER-encoded format.

Parameters

[out]	SigListsSize	A pointer to size of signature list
[out]	SigListOut	A pointer to a callee-allocated buffer with signature lists
[in]	KeyInfoCount	The number of certificate pointer and size pairs inside KeyInfo.
[in]	KeyInfo	A pointer to all certificates, in the format of DER-encoded, to be concatenated into signature lists.

Return values

EFI_SUCCESS	Created signature list from payload successfully.
EFI_NOT_FOUND	Section with key has not been found.
EFI_INVALID_PARAMETER	Embedded key has a wrong format or input pointers are NULL.
Others	Unexpected error happens.

Create a EFI Signature List with data supplied from input argument. The input certificates from KeyInfo parameter should be DER-encoded format.

Parameters

[out]	SigListsSize	A pointer to size of signature list
[out]	SigListOut	A pointer to a callee-allocated buffer with signature lists
[in]	KeyInfoCount	The number of certificate pointer and size pairs inside KeyInfo.
[in]	KeyInfo	A pointer to all certificates, in the format of DER-encoded, to be concatenated into signature lists.

Return values

EFI_SUCCESS	Created signature list from payload successfully.
EFI_NOT_FOUND	Section with key has not been found.
EFI_INVALID_PARAMETER	Embedded key has a wrong format or input pointers are NULL.
Others	Unexpected error happens.

Definition at line 169 of file SecureBootVariableLib.c.

◆ SetSecureBootMode()

EFI_STATUS EFIAPI SetSecureBootMode ( IN UINT8 SecureBootMode )

Set the platform secure boot mode into "Custom" or "Standard" mode.

Parameters

[in] SecureBootMode New secure boot mode: STANDARD_SECURE_BOOT_MODE or CUSTOM_SECURE_BOOT_MODE.

Returns: EFI_SUCCESS The platform has switched to the special mode successfully.; other Fail to operate the secure boot mode.

Set the platform secure boot mode into "Custom" or "Standard" mode.

Parameters

[in] SecureBootMode New secure boot mode: STANDARD_SECURE_BOOT_MODE or CUSTOM_SECURE_BOOT_MODE.

Returns: EFI_SUCCESS The platform has switched to the special mode successfully.; other Fail to operate the secure boot mode.

Definition at line 391 of file SecureBootVariableLib.c.

◆ SetSecureBootVariablesToDefault()

EFI_STATUS EFIAPI SetSecureBootVariablesToDefault ( IN CONST SECURE_BOOT_PAYLOAD_INFO * SecureBootPayload )

Similar to DeleteSecureBootVariables, this function is used to unilaterally force the state of related SB variables (db, dbx, dbt, KEK, PK, etc.) to be the built-in, hardcoded default vars.

Parameters

[in] SecureBootPayload Payload information for secure boot related keys.

Return values

EFI_SUCCESS	SecureBoot keys are now set to defaults.
EFI_ABORTED	SecureBoot keys are not empty. Please delete keys first or follow standard methods of altering keys (ie. use the signing system).
EFI_SECURITY_VIOLATION	Failed to create the PK.
Others	Something failed in one of the subfunctions.

Definition at line 790 of file SecureBootVariableLib.c.

Functions

Detailed Description

Function Documentation

◆ CreateTimeBasedPayload()

◆ DeleteDb()

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

◆ DeleteDbt()

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

◆ DeleteDbx()

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

◆ DeleteKEK()

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

◆ DeletePlatformKey()

@retval other Errors from GetVariable2(), GetTime() and SetVariable()

◆ DeleteSecureBootVariables()

◆ EnrollFromInput()

◆ GetSetupMode()

@retval other Error codes from GetVariable.

◆ IsSecureBootEnabled()

◆ SecureBootCreateDataFromInput()

◆ SetSecureBootMode()

◆ SetSecureBootVariablesToDefault()