MdeModulePkg/Include/Library/LockBoxLib.h

   1 /** @file
   2   This library is only intended to be used by DXE modules that need save
   3   confidential information to LockBox and get it by PEI modules in S3 phase.
   4
   5 Copyright (c) 2010 - 2019, Intel Corporation. All rights reserved.<BR>
   6
   7 SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef _LOCK_BOX_LIB_H_
  12 #define _LOCK_BOX_LIB_H_
  13
  14 /**
  15   This function will save confidential information to lockbox.
  16
  17   @param Guid       the guid to identify the confidential information
  18   @param Buffer     the address of the confidential information
  19   @param Length     the length of the confidential information
  20
  21   @retval RETURN_SUCCESS            the information is saved successfully.
  22   @retval RETURN_INVALID_PARAMETER  the Guid is NULL, or Buffer is NULL, or Length is 0
  23   @retval RETURN_ALREADY_STARTED    the requested GUID already exist.
  24   @retval RETURN_OUT_OF_RESOURCES   no enough resource to save the information.
  25   @retval RETURN_ACCESS_DENIED      it is too late to invoke this interface
  26   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
  27   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
  28 **/
  29 RETURN_STATUS
  30 EFIAPI
  31 SaveLockBox (
  32   IN  GUID                        *Guid,
  33   IN  VOID                        *Buffer,
  34   IN  UINTN                       Length
  35   );
  36
  37 /**
  38   This function will set lockbox attributes.
  39
  40   @param Guid       the guid to identify the confidential information
  41   @param Attributes the attributes of the lockbox
  42
  43   @retval RETURN_SUCCESS            the information is saved successfully.
  44   @retval RETURN_INVALID_PARAMETER  attributes is invalid.
  45   @retval RETURN_NOT_FOUND          the requested GUID not found.
  46   @retval RETURN_ACCESS_DENIED      it is too late to invoke this interface
  47   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
  48   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
  49 **/
  50 RETURN_STATUS
  51 EFIAPI
  52 SetLockBoxAttributes (
  53   IN  GUID                        *Guid,
  54   IN  UINT64                      Attributes
  55   );
  56
  57 //
  58 // With this flag, this LockBox can be restored to this Buffer
  59 // with RestoreAllLockBoxInPlace()
  60 //
  61 #define LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE     BIT0
  62 //
  63 // With this flag, this LockBox can be restored in S3 resume only.
  64 // This LockBox can not be restored after SmmReadyToLock in normal boot
  65 // and after EndOfS3Resume in S3 resume.
  66 // It can not be set together with LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE.
  67 //
  68 #define LOCK_BOX_ATTRIBUTE_RESTORE_IN_S3_ONLY   BIT1
  69
  70 /**
  71   This function will update confidential information to lockbox.
  72
  73   @param Guid   the guid to identify the original confidential information
  74   @param Offset the offset of the original confidential information
  75   @param Buffer the address of the updated confidential information
  76   @param Length the length of the updated confidential information
  77
  78   @retval RETURN_SUCCESS            the information is saved successfully.
  79   @retval RETURN_INVALID_PARAMETER  the Guid is NULL, or Buffer is NULL, or Length is 0.
  80   @retval RETURN_NOT_FOUND          the requested GUID not found.
  81   @retval RETURN_BUFFER_TOO_SMALL   for lockbox without attribute LOCK_BOX_ATTRIBUTE_RESTORE_IN_S3_ONLY,
  82                                     the original buffer to too small to hold new information.
  83   @retval RETURN_OUT_OF_RESOURCES   for lockbox with attribute LOCK_BOX_ATTRIBUTE_RESTORE_IN_S3_ONLY,
  84                                     no enough resource to save the information.
  85   @retval RETURN_ACCESS_DENIED      it is too late to invoke this interface
  86   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
  87   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
  88 **/
  89 RETURN_STATUS
  90 EFIAPI
  91 UpdateLockBox (
  92   IN  GUID                        *Guid,
  93   IN  UINTN                       Offset,
  94   IN  VOID                        *Buffer,
  95   IN  UINTN                       Length
  96   );
  97
  98 /**
  99   This function will restore confidential information from lockbox.
 100
 101   @param Guid   the guid to identify the confidential information
 102   @param Buffer the address of the restored confidential information
 103                 NULL means restored to original address, Length MUST be NULL at same time.
 104   @param Length the length of the restored confidential information
 105
 106   @retval RETURN_SUCCESS            the information is restored successfully.
 107   @retval RETURN_INVALID_PARAMETER  the Guid is NULL, or one of Buffer and Length is NULL.
 108   @retval RETURN_WRITE_PROTECTED    Buffer and Length are NULL, but the LockBox has no
 109                                     LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE attribute.
 110   @retval RETURN_BUFFER_TOO_SMALL   the Length is too small to hold the confidential information.
 111   @retval RETURN_NOT_FOUND          the requested GUID not found.
 112   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
 113   @retval RETURN_ACCESS_DENIED      not allow to restore to the address
 114   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
 115 **/
 116 RETURN_STATUS
 117 EFIAPI
 118 RestoreLockBox (
 119   IN  GUID                        *Guid,
 120   IN  VOID                        *Buffer, OPTIONAL
 121   IN  OUT UINTN                   *Length  OPTIONAL
 122   );
 123
 124 /**
 125   This function will restore confidential information from all lockbox which have RestoreInPlace attribute.
 126
 127   @retval RETURN_SUCCESS            the information is restored successfully.
 128   @retval RETURN_NOT_STARTED        it is too early to invoke this interface
 129   @retval RETURN_UNSUPPORTED        the service is not supported by implementaion.
 130 **/
 131 RETURN_STATUS
 132 EFIAPI
 133 RestoreAllLockBoxInPlace (
 134   VOID
 135   );
 136
 137 #endif