SecurityPkg: Create SecureBootVariableLib.

[mirror_edk2.git] / SecurityPkg / Include / Library / SecureBootVariableLib.h

diff --git a/SecurityPkg/Include/Library/SecureBootVariableLib.h b/SecurityPkg/Include/Library/SecureBootVariableLib.h
new file mode 100644 (file)
index 0000000..6e6d624
--- /dev/null
+++ b/SecurityPkg/Include/Library/SecureBootVariableLib.h
@@ -0,0 +1,153 @@
+/** @file\r
+  Provides a helper functions for creating variable authenticated\r
+  payloads, signature lists related to secure boot keys.\r
+\r
+Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>\r
+(C) Copyright 2018 Hewlett Packard Enterprise Development LP<BR>\r
+Copyright (c) 2021, ARM Ltd. All rights reserved.<BR>\r
+Copyright (c) 2021, Semihalf All rights reserved.<BR>\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\r
+\r
+**/\r
+\r
+#ifndef SECURE_BOOT_VARIABLE_LIB_H_\r
+#define SECURE_BOOT_VARIABLE_LIB_H_\r
+\r
+/**\r
+  Set the platform secure boot mode into "Custom" or "Standard" mode.\r
+\r
+  @param[in]   SecureBootMode        New secure boot mode: STANDARD_SECURE_BOOT_MODE or\r
+                                     CUSTOM_SECURE_BOOT_MODE.\r
+\r
+  @return EFI_SUCCESS                The platform has switched to the special mode successfully.\r
+  @return other                      Fail to operate the secure boot mode.\r
+\r
+--*/\r
+EFI_STATUS\r
+SetSecureBootMode (\r
+  IN  UINT8  SecureBootMode\r
+);\r
+\r
+/**\r
+  Fetches the value of SetupMode variable.\r
+\r
+  @param[out] SetupMode             Pointer to UINT8 for SetupMode output\r
+\r
+  @retval other                     Error codes from GetVariable.\r
+--*/\r
+EFI_STATUS\r
+EFIAPI\r
+GetSetupMode (\r
+  OUT UINT8 *SetupMode\r
+);\r
+\r
+/**\r
+  Create a EFI Signature List with data fetched from section specified as a argument.\r
+  Found keys are verified using RsaGetPublicKeyFromX509().\r
+\r
+  @param[in]        KeyFileGuid    A pointer to to the FFS filename GUID\r
+  @param[out]       SigListsSize   A pointer to size of signature list\r
+  @param[out]       SigListsOut    a pointer to a callee-allocated buffer with signature lists\r
+\r
+  @retval EFI_SUCCESS              Create time based payload successfully.\r
+  @retval EFI_NOT_FOUND            Section with key has not been found.\r
+  @retval EFI_INVALID_PARAMETER    Embedded key has a wrong format.\r
+  @retval Others                   Unexpected error happens.\r
+\r
+--*/\r
+EFI_STATUS\r
+SecureBootFetchData (\r
+    IN  EFI_GUID           *KeyFileGuid,\r
+    OUT UINTN              *SigListsSize,\r
+    OUT EFI_SIGNATURE_LIST **SigListOut\r
+);\r
+\r
+/**\r
+  Create a time based data payload by concatenating the EFI_VARIABLE_AUTHENTICATION_2\r
+  descriptor with the input data. NO authentication is required in this function.\r
+\r
+  @param[in, out]   DataSize       On input, the size of Data buffer in bytes.\r
+                                   On output, the size of data returned in Data\r
+                                   buffer in bytes.\r
+  @param[in, out]   Data           On input, Pointer to data buffer to be wrapped or\r
+                                   pointer to NULL to wrap an empty payload.\r
+                                   On output, Pointer to the new payload date buffer allocated from pool,\r
+                                   it's caller's responsibility to free the memory when finish using it.\r
+\r
+  @retval EFI_SUCCESS              Create time based payload successfully.\r
+  @retval EFI_OUT_OF_RESOURCES     There are not enough memory resources to create time based payload.\r
+  @retval EFI_INVALID_PARAMETER    The parameter is invalid.\r
+  @retval Others                   Unexpected error happens.\r
+\r
+--*/\r
+EFI_STATUS\r
+CreateTimeBasedPayload (\r
+  IN OUT UINTN            *DataSize,\r
+  IN OUT UINT8            **Data\r
+);\r
+\r
+/**\r
+  Clears the content of the 'db' variable.\r
+\r
+  @retval EFI_OUT_OF_RESOURCES      If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails\r
+                                    while VendorGuid is NULL.\r
+  @retval other                     Errors from GetVariable2(), GetTime() and SetVariable()\r
+--*/\r
+EFI_STATUS\r
+EFIAPI\r
+DeleteDb (\r
+  VOID\r
+);\r
+\r
+/**\r
+  Clears the content of the 'dbx' variable.\r
+\r
+  @retval EFI_OUT_OF_RESOURCES      If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails\r
+                                    while VendorGuid is NULL.\r
+  @retval other                     Errors from GetVariable2(), GetTime() and SetVariable()\r
+--*/\r
+EFI_STATUS\r
+EFIAPI\r
+DeleteDbx (\r
+  VOID\r
+);\r
+\r
+/**\r
+  Clears the content of the 'dbt' variable.\r
+\r
+  @retval EFI_OUT_OF_RESOURCES      If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails\r
+                                    while VendorGuid is NULL.\r
+  @retval other                     Errors from GetVariable2(), GetTime() and SetVariable()\r
+--*/\r
+EFI_STATUS\r
+EFIAPI\r
+DeleteDbt (\r
+  VOID\r
+);\r
+\r
+/**\r
+  Clears the content of the 'KEK' variable.\r
+\r
+  @retval EFI_OUT_OF_RESOURCES      If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails\r
+                                    while VendorGuid is NULL.\r
+  @retval other                     Errors from GetVariable2(), GetTime() and SetVariable()\r
+--*/\r
+EFI_STATUS\r
+EFIAPI\r
+DeleteKEK (\r
+  VOID\r
+);\r
+\r
+/**\r
+  Clears the content of the 'PK' variable.\r
+\r
+  @retval EFI_OUT_OF_RESOURCES      If memory allocation for EFI_VARIABLE_AUTHENTICATION_2 fails\r
+                                    while VendorGuid is NULL.\r
+  @retval other                     Errors from GetVariable2(), GetTime() and SetVariable()\r
+--*/\r
+EFI_STATUS\r
+EFIAPI\r
+DeletePlatformKey (\r
+  VOID\r
+);\r
+#endif\r